diff --git a/eslint.config.ts b/eslint.config.ts index 1f7790fb..7f7beeab 100644 --- a/eslint.config.ts +++ b/eslint.config.ts @@ -50,8 +50,28 @@ const layerMessages = { "an adapter implements an application port and never imports UI or bootstrap (adapters-do-not-know-presentation). Pass what it needs through the port.", } as const; +// 07-01. Deprecated aliases stay exported for downstream projects until they +// are removed, but nothing in this repository imports them. The ESLint parser +// here has no type information, so this stands in for a no-deprecated rule. +const deprecatedAliasImports = [ + { + group: ["**/contracts/boundary-mapper.ts", "**/contracts/boundary-mapper"], + importNames: ["MappingResult"], + message: + "deprecated alias: import BoundaryMappingResult. The contract-side MappingResult lives in external-contract-runtime.ts.", + }, + { + group: ["**/contracts/errors.ts", "**/contracts/errors"], + importNames: ["ApiFailure"], + message: "deprecated alias: import AppFailure.", + }, +]; + function restrictedImports(patterns: readonly string[], message: string) { - return ["error", { patterns: [{ group: [...patterns], message }] }]; + return [ + "error", + { patterns: [{ group: [...patterns], message }, ...deprecatedAliasImports] }, + ]; } const restrictedBrowserDataProperties = [ @@ -553,6 +573,14 @@ export default [ "browser-data-boundary/no-capability-alias": "error", }, }, + { + // 07-01. Every file outside a layer rule; the layer rules below replace + // this entry and carry the same aliases through restrictedImports. + files: [`src/**/*.${sourceExtensions}`, `tests/**/*.${sourceExtensions}`], + rules: { + "no-restricted-imports": ["error", { patterns: deprecatedAliasImports }], + }, + }, { files: [`src/domain/**/*.${sourceExtensions}`], rules: { diff --git a/src/adapters/http/client.ts b/src/adapters/http/client.ts index f002ca4c..2db6b5ad 100644 --- a/src/adapters/http/client.ts +++ b/src/adapters/http/client.ts @@ -41,11 +41,11 @@ import type { ClockPort } from "../../application/ports/clock-port.ts"; import type { DiagnosticsPort } from "../../application/ports/diagnostics-port.ts"; import type { TelemetryPort } from "../../application/ports/telemetry-port.ts"; import type { ApiOperation } from "../../contracts/api-operations.ts"; -import type { ApiFailure, FailureKind } from "../../contracts/errors.ts"; +import type { AppFailure, FailureKind } from "../../contracts/errors.ts"; import type { OperationRequestInput } from "./request-builder.ts"; import { readBoundedJson } from "./bounded-json.ts"; import { admitCredentialHeaders } from "./http-contract-bridge.ts"; -import type { MappingResult } from "../../contracts/boundary-mapper.ts"; +import type { BoundaryMappingResult } from "../../contracts/boundary-mapper.ts"; import { createRestProviderProfile, resolveRestSecurityProfiles, @@ -70,7 +70,7 @@ const noAuthSession: HttpAuthSession = Object.freeze({ onUnauthenticated: () => {}, } satisfies HttpAuthSession); -export type HttpFailure = ApiFailure; +export type HttpFailure = AppFailure; export type Scheduler = Readonly<{ setTimeout(callback: () => void, milliseconds: number): unknown; @@ -104,7 +104,7 @@ export type HttpClientDependencies = Readonly<{ mapPayload?: ( operationId: string, payload: unknown, - ) => MappingResult; + ) => BoundaryMappingResult; idempotencyKeyFactory?: () => string; /** * Default total deadline for an operation without its own `timeoutMs`. Not a @@ -866,7 +866,7 @@ async function parseResponse( mapPayload: ( operationId: string, payload: unknown, - ) => MappingResult, + ) => BoundaryMappingResult, now: number, ): Promise { // R3-1. Retry-After is read only where the retry policy honors it; 502/504 diff --git a/src/adapters/http/feature-http-binding.ts b/src/adapters/http/feature-http-binding.ts index 856265f8..51b060a9 100644 --- a/src/adapters/http/feature-http-binding.ts +++ b/src/adapters/http/feature-http-binding.ts @@ -2,11 +2,11 @@ import type { InstalledHttpContract, } from "../../contracts/external-contract-runtime.ts"; import type { Result } from "../../contracts/result.ts"; -import type { MappingResult } from "../../contracts/boundary-mapper.ts"; +import type { BoundaryMappingResult } from "../../contracts/boundary-mapper.ts"; import { createFailure, kindForStatus, - type ApiFailure, + type AppFailure, type FailureEffectCertainty, type FailureKind, type ValidationIssue, @@ -90,7 +90,7 @@ type FeatureHttpOperationSpec< routeId: RouteId; mapSuccess( value: HttpContractWireOutput, - ): MappingResult; + ): BoundaryMappingResult; mapProblem?( problem: HttpContractProblem, metadata: SafeResponseMetadata, @@ -221,7 +221,7 @@ export type FeatureHttpBinding< intent?: MutationIntent; execution?: ExecutionContext; }>, - ): Promise, ApiFailure>>; + ): Promise, AppFailure>>; }>; /** @@ -254,7 +254,7 @@ export function createFeatureHttpBinding< intent?: MutationIntent; execution?: ExecutionContext; }> = {}, - ): Promise, ApiFailure>> { + ): Promise, AppFailure>> { const operation = operations[operationId]; type SelectedOperation = Operations[OperationId]; type Input = OperationInput; @@ -277,7 +277,7 @@ export function createFeatureHttpBinding< }); return projectExecutionOutcome( operation.operationId, - operation.mapSuccess as (value: WireOutput) => MappingResult, + operation.mapSuccess as (value: WireOutput) => BoundaryMappingResult, operation.mapProblem as | (( problem: Problem, @@ -296,7 +296,7 @@ export function createFeatureHttpBinding< */ function projectExecutionOutcome( operationId: string, - mapSuccess: (value: WireOutput) => MappingResult, + mapSuccess: (value: WireOutput) => BoundaryMappingResult, mapProblem: | (( problem: Problem, @@ -304,7 +304,7 @@ function projectExecutionOutcome( ) => FeatureHttpProblemMapping | undefined) | undefined, outcome: HttpExecutionOutcome, -): Result { +): Result { const projected = projectOutcome(operationId, mapSuccess, mapProblem, outcome); const requestId = "metadata" in outcome @@ -320,7 +320,7 @@ function projectExecutionOutcome( function projectOutcome( operationId: string, - mapSuccess: (value: WireOutput) => MappingResult, + mapSuccess: (value: WireOutput) => BoundaryMappingResult, mapProblem: | (( problem: Problem, @@ -328,13 +328,13 @@ function projectOutcome( ) => FeatureHttpProblemMapping | undefined) | undefined, outcome: HttpExecutionOutcome, -): Result { +): Result { // A throwing feature mapper is a mapping defect, not a transport failure: it // must not reject and lose the effect the server already confirmed. const mapperThrew = ( effect: FailureEffectCertainty, httpStatus: number, - ): Result => + ): Result => failure( "MAPPING_CONTRACT_VIOLATION", operationId, @@ -343,7 +343,7 @@ function projectOutcome( ); switch (outcome.kind) { case "SUCCESS": { - let mapped: MappingResult; + let mapped: BoundaryMappingResult; try { mapped = mapSuccess(outcome.value); } catch { @@ -484,7 +484,7 @@ function failure( effect?: FailureEffectCertainty; validationIssues?: readonly ValidationIssue[]; }> = {}, -): Result { +): Result { return Object.freeze({ ok: false as const, error: createFailure(kind, operationId, 0, { code, ...details }), diff --git a/src/adapters/http/resource-mapper.ts b/src/adapters/http/resource-mapper.ts index 3d31df00..ea4a71e4 100644 --- a/src/adapters/http/resource-mapper.ts +++ b/src/adapters/http/resource-mapper.ts @@ -1,11 +1,11 @@ import { mappingFailure, - type MappingResult, + type BoundaryMappingResult, } from "../../contracts/boundary-mapper.ts"; export function mapOperationPayload( _operationId: string, _payload: unknown, -): MappingResult { +): BoundaryMappingResult { return mappingFailure("MAPPING_INVARIANT_REJECTED"); } diff --git a/src/application/ports/query-cache-port.ts b/src/application/ports/query-cache-port.ts index 0862bb2b..753033e4 100644 --- a/src/application/ports/query-cache-port.ts +++ b/src/application/ports/query-cache-port.ts @@ -1,12 +1,12 @@ -import type { ApiFailure } from "../../contracts/errors.ts"; +import type { AppFailure } from "../../contracts/errors.ts"; export type QueryCacheReadResult = | Readonly<{ ok: true; value: unknown }> - | Readonly<{ ok: false; error: ApiFailure }>; + | Readonly<{ ok: false; error: AppFailure }>; export type QueryCacheWriteResult = | Readonly<{ ok: true }> - | Readonly<{ ok: false; error: ApiFailure }>; + | Readonly<{ ok: false; error: AppFailure }>; export type QueryCachePort = Readonly<{ read(key: readonly unknown[]): QueryCacheReadResult; diff --git a/src/application/ports/storage-port.ts b/src/application/ports/storage-port.ts index e6b0e44d..ac7ee97d 100644 --- a/src/application/ports/storage-port.ts +++ b/src/application/ports/storage-port.ts @@ -1,12 +1,12 @@ -import type { ApiFailure } from "../../contracts/errors.ts"; +import type { AppFailure } from "../../contracts/errors.ts"; export type StorageReadResult = | Readonly<{ ok: true; value: unknown }> - | Readonly<{ ok: false; error: ApiFailure }>; + | Readonly<{ ok: false; error: AppFailure }>; export type StorageMutationResult = | Readonly<{ ok: true }> - | Readonly<{ ok: false; error: ApiFailure; fallback?: string }>; + | Readonly<{ ok: false; error: AppFailure; fallback?: string }>; export type StoragePort = Readonly<{ read(logicalName: string): StorageReadResult; diff --git a/src/contracts/boundary-mapper.ts b/src/contracts/boundary-mapper.ts index 1116d927..f8114aa8 100644 --- a/src/contracts/boundary-mapper.ts +++ b/src/contracts/boundary-mapper.ts @@ -6,20 +6,24 @@ export type MappingFailureCode = | "OUTPUT_LIMIT_EXCEEDED"; /** - * D-15. The boundary mapper's own result: a flat failure `code`. The canonical - * mapping result is `MappingResult` in `external-contract-runtime.ts` - * (`error: { kind, code }`); convert with `toContractMappingResult`. + * D-15, 07-01. What a feature mapper returns: a flat failure `code` from the + * closed `MappingFailureCode` set. The HTTP binding (`mapSuccess`) and every + * helper below use this shape. The contract-package side has its own result, + * `MappingResult` in `external-contract-runtime.ts` (`error: { kind, code }`, + * free code); convert to it with `toContractMappingResult`. */ export type BoundaryMappingResult = | Readonly<{ ok: true; value: Value }> | Readonly<{ ok: false; code: MappingFailureCode }>; /** - * Compatible alias kept for existing importers. + * Compatible alias kept for downstream importers. It shares its name with the + * contract-side `MappingResult` but not its shape. * - * @deprecated Use `BoundaryMappingResult`. Remove in the next minor release - * once no module imports `MappingResult` from this file (owner: - * frontend-platform). + * @deprecated Use `BoundaryMappingResult`. Nothing in this repository imports + * it (07-01, enforced by `no-restricted-imports` in eslint.config.ts). + * Removing it breaks downstream importers; do it in a minor release with a + * CHANGELOG [계약] entry (owner: frontend-platform). */ export type MappingResult = BoundaryMappingResult; @@ -44,7 +48,7 @@ export type BoundaryMapper = Readonly<{ outputContractId: string; owner: string; maxOutputItems: number; - map(input: Input): MappingResult; + map(input: Input): BoundaryMappingResult; }>; export type InstalledBoundaryMapper = BoundaryMapper; @@ -80,7 +84,7 @@ export function mapWithBoundaryRegistry( mapperId: string, input: unknown, registry: Readonly>, -): MappingResult { +): BoundaryMappingResult { const mapper = Object.hasOwn(registry, mapperId) ? registry[mapperId] : undefined; @@ -92,10 +96,10 @@ export function mapWithBoundaryRegistry( } } -export function mappingSuccess(value: Value): MappingResult { +export function mappingSuccess(value: Value): BoundaryMappingResult { return Object.freeze({ ok: true, value }); } -export function mappingFailure(code: MappingFailureCode): MappingResult { +export function mappingFailure(code: MappingFailureCode): BoundaryMappingResult { return Object.freeze({ ok: false, code }); } diff --git a/src/contracts/errors.ts b/src/contracts/errors.ts index a434a261..04ad9758 100644 --- a/src/contracts/errors.ts +++ b/src/contracts/errors.ts @@ -137,8 +137,10 @@ export type AppFailure = Readonly<{ /** * Backward-compatible transport-facing name. * - * @deprecated Use `AppFailure`. Remove in the next minor release once - * `grep -rw ApiFailure src` finds only this line (owner: frontend-platform). + * @deprecated Use `AppFailure`. Nothing in this repository imports it (07-01, + * enforced by `no-restricted-imports` in eslint.config.ts). Removing it breaks + * downstream importers; do it in a minor release with a CHANGELOG [계약] + * entry (owner: frontend-platform). */ export type ApiFailure = AppFailure; diff --git a/src/contracts/external-contract-runtime.ts b/src/contracts/external-contract-runtime.ts index 0d2d96c2..96131dd9 100644 --- a/src/contracts/external-contract-runtime.ts +++ b/src/contracts/external-contract-runtime.ts @@ -40,9 +40,12 @@ export const HTTP_EXECUTION_CEILINGS = Object.freeze({ }); /* - * D-15. The validator protocol and `MappingResult` below are the canonical - * shapes. `RuntimeSchemaCodec` (`schema-registry.ts`) and the boundary - * mapper's result (`boundary-mapper.ts`) are adapters over them. + * D-15. The validator protocol below is the canonical shape; + * `RuntimeSchemaCodec` (`schema-registry.ts`) adapts over it. `MappingResult` + * below is the contract-package side of a mapping result. Feature mappers and + * the HTTP binding return `BoundaryMappingResult` (`boundary-mapper.ts`) + * instead, whose failure code is a closed set; `toContractMappingResult` + * converts one into this shape (07-01). */ export type RuntimeValidationIssue = Readonly<{ path: readonly (string | number)[]; diff --git a/src/features/reference-feature/README.md b/src/features/reference-feature/README.md index c6afd373..3fc8d7b0 100644 --- a/src/features/reference-feature/README.md +++ b/src/features/reference-feature/README.md @@ -24,8 +24,9 @@ augmentation으로 `"reference-feature": ReferenceFeatureInput`을 기여하므 `src/contracts/result.ts`의 `Result`로 반환한다. `src/application/result.ts`는 기존 호출자를 위한 deprecated migration shim일 뿐 새 코드의 import 경로가 아니다. `AppFailure.kind`는 -`ERROR_REGISTRY` key에서 파생된 닫힌 vocabulary이며, transport 호환 이름인 -`ApiFailure`는 같은 type의 alias다. +`ERROR_REGISTRY` key에서 파생된 닫힌 vocabulary다. 폐기된 별칭 `ApiFailure` +대신 `AppFailure`를 import한다(lint가 막는다). mapper는 `boundary-mapper.ts`의 +`BoundaryMappingResult`를 반환한다. HTTP adapter는 `src/adapters/http/feature-http-binding.ts`의 capability-specific typed binding을 사용한다. feature는 operation ID, route ID, request type, 성공 diff --git a/src/features/reference-feature/application/reference-error.ts b/src/features/reference-feature/application/reference-error.ts index 7a84685b..f55fde53 100644 --- a/src/features/reference-feature/application/reference-error.ts +++ b/src/features/reference-feature/application/reference-error.ts @@ -2,7 +2,7 @@ import { defineAppError, type AppError, } from "../../../platform/errors/app-error.ts"; -import type { ApiFailure } from "../../../contracts/errors.ts"; +import type { AppFailure } from "../../../contracts/errors.ts"; /** * Spec §17–§19. The reference feature's own domain errors. @@ -57,7 +57,7 @@ export const REFERENCE_ERRORS = Object.freeze({ * Anything that is not a reference domain outcome stays `null`: the platform * error mapping, not this feature, owns transport/contract failures. */ -export function toReferenceError(failure: ApiFailure): ReferenceError | null { +export function toReferenceError(failure: AppFailure): ReferenceError | null { switch (failure.kind) { case "NOT_FOUND": return REFERENCE_ERRORS.NOT_FOUND; diff --git a/src/features/reference-feature/application/reference-feature-api.ts b/src/features/reference-feature/application/reference-feature-api.ts index eadce0fa..22bb7057 100644 --- a/src/features/reference-feature/application/reference-feature-api.ts +++ b/src/features/reference-feature/application/reference-feature-api.ts @@ -8,7 +8,7 @@ import type { ReferenceResource } from "../domain/reference-resource.ts"; import type { MutationIntent } from "../../../contracts/mutation-intent.ts"; import type { ExecutionContext } from "../../../platform/execution/execution-context.ts"; import type { TelemetryPort } from "../../../platform/telemetry/telemetry-port.ts"; -import type { ApiFailure } from "../../../contracts/errors.ts"; +import type { AppFailure } from "../../../contracts/errors.ts"; import { REFERENCE_FEATURE_ID } from "../contracts/reference-feature-contract.ts"; /** @@ -75,13 +75,13 @@ export type ReferenceGateway = Readonly<{ */ export type ReferenceLoadFailedPayload = Readonly<{ operation: "list" | "detail"; - reason: ApiFailure["kind"]; + reason: AppFailure["kind"]; }>; function reportLoadFailure( telemetry: TelemetryPort | undefined, operation: ReferenceLoadFailedPayload["operation"], - failure: ApiFailure, + failure: AppFailure, context: ReferenceCallContext | undefined, ): void { if (!telemetry || failure.kind === "REQUEST_ABORTED") return; diff --git a/src/features/reference-feature/contracts/reference-mapper.ts b/src/features/reference-feature/contracts/reference-mapper.ts index 8645f7ea..3f607954 100644 --- a/src/features/reference-feature/contracts/reference-mapper.ts +++ b/src/features/reference-feature/contracts/reference-mapper.ts @@ -6,7 +6,7 @@ import { mappingFailure, mappingSuccess, type InstalledBoundaryMapper, - type MappingResult, + type BoundaryMappingResult, } from "../../../contracts/boundary-mapper.ts"; import type { ReferenceResourceDto } from "./reference-schemas.ts"; @@ -23,7 +23,7 @@ export type ReferenceResourceView = Readonly<{ */ export function mapReferenceResourcePayload( dto: ReferenceResourceDto, -): MappingResult { +): BoundaryMappingResult { try { return mappingSuccess( createReferenceResource({ @@ -39,7 +39,7 @@ export function mapReferenceResourcePayload( export function mapReferenceResourceListPayload( payload: readonly ReferenceResourceDto[], -): MappingResult { +): BoundaryMappingResult { const output: ReferenceResource[] = []; for (const item of payload) { const mapped = mapReferenceResourcePayload(item); @@ -61,7 +61,7 @@ function isReferenceResourceDto(value: unknown): value is ReferenceResourceDto { function mapUnknownReferenceResourcePayload( value: unknown, -): MappingResult { +): BoundaryMappingResult { return isReferenceResourceDto(value) ? mapReferenceResourcePayload(value) : mappingFailure("MAPPING_INVARIANT_REJECTED"); @@ -69,7 +69,7 @@ function mapUnknownReferenceResourcePayload( function mapUnknownReferenceResourceListPayload( value: unknown, -): MappingResult { +): BoundaryMappingResult { if ( !Array.isArray(value) || value.length > 100 || @@ -92,7 +92,7 @@ function mapUnknownReferenceResourceListPayload( export function mapReferenceOperation( operationId: string, payload: unknown, -): MappingResult { +): BoundaryMappingResult { if (operationId === "LIST_REFERENCE_RESOURCES") { return mapUnknownReferenceResourceListPayload(payload); } diff --git a/tests/features/reference-feature/reference-http-gateway.test.ts b/tests/features/reference-feature/reference-http-gateway.test.ts index 77b46f88..182fd35c 100644 --- a/tests/features/reference-feature/reference-http-gateway.test.ts +++ b/tests/features/reference-feature/reference-http-gateway.test.ts @@ -1,7 +1,7 @@ import { describe, expect, it } from "vitest"; import type { Result } from "../../../src/contracts/result.ts"; -import { createFailure, type ApiFailure } from "../../../src/contracts/errors.ts"; +import { createFailure, type AppFailure } from "../../../src/contracts/errors.ts"; import { createReferenceHttpGateway, type ReferenceHttpBinding, @@ -23,7 +23,7 @@ const resources = Object.freeze({ type ScriptedResult = Result< ReferenceResource | readonly ReferenceResource[], - ApiFailure + AppFailure >; function scriptedBinding(results: ScriptedResult[]) {