donghyeon.kang/clean-architecture-frontend-template
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

fix: make the architecture and documentation rules say what is actually true

Browse Source 
Three boundaries the layer contract declares had no executable rule behind
them, so the code drifted across all three while every gate stayed green.

`src/contracts` reached back up into `src/application` for the shared `Result`
carrier and the compatibility predicate. Neither package owned the shared
vocabulary and the dependency pointed both ways. Both now live in contracts —
the lower package — and application re-exports them, so no caller moves.

A concrete adapter was not supposed to depend on another concrete adapter, but
only adapter-to-presentation was enforced, and `diagnostics` imported a guard
out of `telemetry`. The guard belongs to neither, so it moved to the adapter
kernel. Stating the rule needed the checker to resolve `$1` in a `to` pattern
against the importing module's own directory; the alternative is one rule per
adapter group, which silently stops covering a group the moment one is added.

Product assembly leaks out of bootstrap: generic presentation reads the
installed-feature registries. That is a real refactor, so the rule freezes the
exact set of modules doing it today rather than pretending it is fixed — a new
edge fails. The two remaining open edges are named in the config, not silent.

Each rule was verified by introducing the violation it forbids and confirming
the gate rejects it.

The documentation drifted the same way. README and the manual accessibility
checklist both said six routes while ten were registered, which left the
platform overview and three reference-resource screens outside the declared
manual review scope without anyone deciding they should be. The scope is now
derived from the route registry by `verify:documentation`, so the sentence
cannot outlive the registry again. The review ledger also named a canonical
path that does not exist in this tree; it is upstream provenance, and it now
says so instead of looking like a broken repository reference.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-08-15 17:23:10 +09:00
co-authored by Claude Opus 5
parent 7485cd86e4
commit 3ea3397691
27 changed files with 428 additions and 172 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/adapters/diagnostics/bounded-diagnostics.ts
+1 -1
View File
@@ -6,7 +6,7 @@ import {
type DiagnosticRecordInput,
} from "../../contracts/diagnostics.ts";
import { projectTelemetryEvent } from "../../contracts/telemetry.ts";
import { assertBoundedCapacity } from "../telemetry/best-effort-telemetry.ts";
import { assertBoundedCapacity } from "../platform/bounded-capacity.ts";
export const noOpDiagnostics: DiagnosticsPort = Object.freeze({
record() {},
src/adapters/platform/bounded-capacity.ts
+21
View File
@@ -0,0 +1,21 @@
/**
* N-11. A non-finite or fractional capacity silently disables eviction, so it is
* a construction-time configuration error rather than a runtime drop.
*
* This lives in the adapter kernel rather than inside the telemetry adapter:
* the diagnostics adapter needs the same guard, and importing it from telemetry
* made one concrete adapter depend on another for a rule that belongs to
* neither of them.
*/
export function assertBoundedCapacity(
value: number,
ceiling: number,
label: string,
): number {
if (!Number.isSafeInteger(value) || value < 1 || value > ceiling) {
throw new TypeError(
`${label} must be a safe integer between 1 and ${ceiling}`,
);
}
return value;
}
src/adapters/telemetry/best-effort-telemetry.ts
+3 -16
View File
@@ -5,6 +5,7 @@ import type {
TelemetryEventName,
} from "../../contracts/telemetry.ts";
import type { TelemetryPort } from "../../application/ports/telemetry-port.ts";
import { assertBoundedCapacity } from "../platform/bounded-capacity.ts";
export type TelemetryAdapter = TelemetryPort &
Readonly<{
@@ -45,22 +46,8 @@ type TelemetryLifecycle = "ACTIVE" | "DISPOSED";
/** N-11. Documented absolute ceiling for the in-memory best-effort queue. */
export const MAX_TELEMETRY_QUEUE = 10_000;
/**
* N-11. A non-finite or fractional capacity silently disables eviction, so it is
* a construction-time configuration error rather than a runtime drop.
*/
export function assertBoundedCapacity(
value: number,
ceiling: number,
label: string,
): number {
if (!Number.isSafeInteger(value) || value < 1 || value > ceiling) {
throw new TypeError(
`${label} must be a safe integer between 1 and ${ceiling}`,
);
}
return value;
}
export { assertBoundedCapacity } from "../platform/bounded-capacity.ts";
export function createTelemetryAdapter(
options: TelemetryAdapterOptions,
src/application/policies/compatibility.ts
+21 -107
View File
@@ -1,107 +1,21 @@
export const COMPATIBILITY_TUPLE_FIELDS = Object.freeze([
"buildId",
"configSchemaVersion",
"apiContractVersion",
"assetManifestHash",
"releaseId",
] as const);
export type CompatibilityTupleField =
(typeof COMPATIBILITY_TUPLE_FIELDS)[number];
export type CompatibilityTuple = Readonly<
Record<CompatibilityTupleField, string>
>;
export type NumericVersion = Readonly<{
major: number;
minor: number;
patch: number;
}>;
export function parseNumericVersion(version: string): NumericVersion | null {
const match = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(version);
if (!match) return null;
return {
major: Number(match[1]),
minor: Number(match[2] ?? 0),
patch: Number(match[3] ?? 0),
};
}
export function isVersionCompatible(
supported: string,
actual: string,
): boolean {
const expected = parseNumericVersion(supported);
const candidate = parseNumericVersion(actual);
if (!expected || !candidate) return false;
return (
expected.major === candidate.major &&
candidate.minor >= expected.minor
);
}
export function verifyCompatibilityTuple(input: Readonly<{
frontend: CompatibilityTuple;
runtime: CompatibilityTuple;
}>) {
const mismatches: CompatibilityTupleField[] = [];
if (input.frontend.buildId !== input.runtime.buildId) mismatches.push("buildId");
if (
!isVersionCompatible(
input.frontend.configSchemaVersion,
input.runtime.configSchemaVersion,
)
) {
mismatches.push("configSchemaVersion");
}
if (
!isVersionCompatible(
input.frontend.apiContractVersion,
input.runtime.apiContractVersion,
)
) {
mismatches.push("apiContractVersion");
}
if (input.frontend.assetManifestHash !== input.runtime.assetManifestHash) {
mismatches.push("assetManifestHash");
}
const releaseWarning: "releaseId" | null =
input.frontend.releaseId === input.runtime.releaseId
? null
: "releaseId";
return Object.freeze({
compatible: mismatches.length === 0,
mismatches: Object.freeze(mismatches),
warnings: Object.freeze(releaseWarning ? [releaseWarning] : []),
});
}
export type ObjectSchemaShape = Readonly<{
required?: readonly string[];
properties?: Readonly<Record<string, unknown>>;
}>;
export type SchemaChangeClassification = "breaking" | "additive" | "none";
export function classifyObjectSchemaChange(
before: ObjectSchemaShape,
after: ObjectSchemaShape,
): SchemaChangeClassification {
const beforeRequired = new Set(before.required ?? []);
const afterRequired = new Set(after.required ?? []);
const removedProperties = Object.keys(before.properties ?? {}).filter(
(key) => !(key in (after.properties ?? {})),
);
const addedRequired = [...afterRequired].filter(
(key) => !beforeRequired.has(key),
);
if (removedProperties.length > 0 || addedRequired.length > 0) return "breaking";
const addedProperties = Object.keys(after.properties ?? {}).filter(
(key) => !(key in (before.properties ?? {})),
);
return addedProperties.length > 0 ? "additive" : "none";
}
/**
* Release compatibility comparison.
*
* The implementation lives in `src/contracts/compatibility.ts`: it is a pure
* predicate over release tokens with no application state, and
* `src/contracts/release-tokens.ts` needs it, which previously made contracts
* import the application layer. This module re-exports it for application-side
* and script-side callers.
*/
export {
COMPATIBILITY_TUPLE_FIELDS,
classifyObjectSchemaChange,
isVersionCompatible,
parseNumericVersion,
verifyCompatibilityTuple,
type CompatibilityTuple,
type CompatibilityTupleField,
type NumericVersion,
type ObjectSchemaShape,
type SchemaChangeClassification,
} from "../../contracts/compatibility.ts";
src/application/policies/promotion-readiness.ts
+3
View File
@@ -20,6 +20,9 @@ export const PROMOTION_FORMULA = Object.freeze({
"FE-GATE-015",
"FE-GATE-019",
"FE-GATE-026",
// FE-GATE-027. A candidate is only release-ready once it has been admitted
// to a named environment; coherence alone never proved it belonged there.
"FE-GATE-027",
]),
PROD_PROMOTION_READY: Object.freeze([
"FE-GATE-016",
src/application/result.ts
+8 -5
View File
@@ -1,10 +1,13 @@
import type { AppFailure } from "../contracts/errors.ts";
/**
* The single success/failure carrier used across application input boundaries.
* Adapters map technology-specific errors to an application failure before
* constructing this value.
*
* The type itself lives in `src/contracts` because both layers need it and
* neither owns it: `src/contracts/server-state.ts` and
* `src/contracts/cursor-pagination.ts` reached back into the application layer
* for it, which made the ownership of the shared vocabulary ambiguous in both
* directions. Contracts is the lower of the two, so the shared shape sits there
* and this module re-exports it for every existing application-side importer.
*/
export type Result<Value, Failure = AppFailure> =
| Readonly<{ ok: true; value: Value }>
| Readonly<{ ok: false; error: Failure }>;
export type { Result } from "../contracts/result.ts";
src/contracts/compatibility.ts
+107
View File
@@ -0,0 +1,107 @@
export const COMPATIBILITY_TUPLE_FIELDS = Object.freeze([
"buildId",
"configSchemaVersion",
"apiContractVersion",
"assetManifestHash",
"releaseId",
] as const);
export type CompatibilityTupleField =
(typeof COMPATIBILITY_TUPLE_FIELDS)[number];
export type CompatibilityTuple = Readonly<
Record<CompatibilityTupleField, string>
>;
export type NumericVersion = Readonly<{
major: number;
minor: number;
patch: number;
}>;
export function parseNumericVersion(version: string): NumericVersion | null {
const match = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(version);
if (!match) return null;
return {
major: Number(match[1]),
minor: Number(match[2] ?? 0),
patch: Number(match[3] ?? 0),
};
}
export function isVersionCompatible(
supported: string,
actual: string,
): boolean {
const expected = parseNumericVersion(supported);
const candidate = parseNumericVersion(actual);
if (!expected || !candidate) return false;
return (
expected.major === candidate.major &&
candidate.minor >= expected.minor
);
}
export function verifyCompatibilityTuple(input: Readonly<{
frontend: CompatibilityTuple;
runtime: CompatibilityTuple;
}>) {
const mismatches: CompatibilityTupleField[] = [];
if (input.frontend.buildId !== input.runtime.buildId) mismatches.push("buildId");
if (
!isVersionCompatible(
input.frontend.configSchemaVersion,
input.runtime.configSchemaVersion,
)
) {
mismatches.push("configSchemaVersion");
}
if (
!isVersionCompatible(
input.frontend.apiContractVersion,
input.runtime.apiContractVersion,
)
) {
mismatches.push("apiContractVersion");
}
if (input.frontend.assetManifestHash !== input.runtime.assetManifestHash) {
mismatches.push("assetManifestHash");
}
const releaseWarning: "releaseId" | null =
input.frontend.releaseId === input.runtime.releaseId
? null
: "releaseId";
return Object.freeze({
compatible: mismatches.length === 0,
mismatches: Object.freeze(mismatches),
warnings: Object.freeze(releaseWarning ? [releaseWarning] : []),
});
}
export type ObjectSchemaShape = Readonly<{
required?: readonly string[];
properties?: Readonly<Record<string, unknown>>;
}>;
export type SchemaChangeClassification = "breaking" | "additive" | "none";
export function classifyObjectSchemaChange(
before: ObjectSchemaShape,
after: ObjectSchemaShape,
): SchemaChangeClassification {
const beforeRequired = new Set(before.required ?? []);
const afterRequired = new Set(after.required ?? []);
const removedProperties = Object.keys(before.properties ?? {}).filter(
(key) => !(key in (after.properties ?? {})),
);
const addedRequired = [...afterRequired].filter(
(key) => !beforeRequired.has(key),
);
if (removedProperties.length > 0 || addedRequired.length > 0) return "breaking";
const addedProperties = Object.keys(after.properties ?? {}).filter(
(key) => !(key in (before.properties ?? {})),
);
return addedProperties.length > 0 ? "additive" : "none";
}
src/contracts/cursor-pagination.ts
+1 -1
View File
@@ -1,4 +1,4 @@
import type { Result } from "../application/result.ts";
import type { Result } from "./result.ts";
export type CursorPage<Value> = Readonly<{
items: readonly Value[];
src/contracts/release-tokens.ts
+1 -1
View File
@@ -1,4 +1,4 @@
import { verifyCompatibilityTuple } from "../application/policies/compatibility.ts";
import { verifyCompatibilityTuple } from "./compatibility.ts";
export const RELEASE_TOKEN_REGISTRY = Object.freeze({
appVersion: token("appVersion", "manifest", "human release label"),
src/contracts/result.ts
+15
View File
@@ -0,0 +1,15 @@
import type { AppFailure } from "./errors.ts";
/**
* The single success/failure carrier used across application input boundaries.
* Adapters map technology-specific errors to an application failure before
* constructing this value.
*
* It lives in `src/contracts` because it is shared vocabulary rather than
* application behaviour: contracts modules describe results too, and reaching
* up into `src/application` for the shape made the dependency between the two
* packages point both ways. `src/application/result.ts` re-exports it.
*/
export type Result<Value, Failure = AppFailure> =
| Readonly<{ ok: true; value: Value }>
| Readonly<{ ok: false; error: Failure }>;
src/contracts/server-state.ts
+1 -1
View File
@@ -1,4 +1,4 @@
import type { Result } from "../application/result.ts";
import type { Result } from "./result.ts";
import type { QueryInvalidationTopic } from "./query-invalidation.ts";
import {
createBoundQueryKey,