chore(review): 1103 release·CI·성능 조치 브랜치를 합친다

Refs: docs/reviews/2026-11-03-maturity-review/README.md 12-07 13-01~13-03 13-05 15-02~15-07

# Conflicts:
#	docs/manual/03-outside-feature-folder.md
#	docs/operations/performance-evidence.md
#	scripts/lib/hosting-probe.ts
This commit is contained in:
DongHyeonka
2026-11-04 23:10:59 +09:00
45 changed files with 3393 additions and 1732 deletions
+100
View File
@@ -0,0 +1,100 @@
import { validateVulnerabilityReport } from "./supply-chain.ts";
/**
* 1103/13-03. The vulnerability verdict belongs to the external provider of
* the production promotion (signed, independent of the build). Without a
* provider nothing told the project that its lockfile already broke the
* template's own policy (high and above, no exception). This summary is the
* early signal: it reads `pnpm audit --json` and applies that policy, so it
* names what the promotion would refuse. It does not replace the provider and
* blocks nothing.
*/
export type AdvisoryStatus = "PASS" | "POLICY_VIOLATION" | "UNVERIFIED";
type Severity = "critical" | "high" | "moderate" | "low" | "info";
type SeverityCounts = Record<Severity, number>;
export type DependencyAdvisorySummary = Readonly<{
status: AdvisoryStatus;
reason: string | null;
counts: Readonly<{ production: SeverityCounts; development: SeverityCounts }>;
/** Findings the vulnerability policy would block at promotion: `id:package@version:severity`. */
blocking: readonly string[];
advisories: readonly Readonly<{
id: string;
packageName: string;
versions: readonly string[];
severity: string;
development: boolean;
patchedVersions: string;
}>[];
}>;
const SEVERITIES: readonly Severity[] = ["critical", "high", "moderate", "low", "info"];
function isRecord(value: unknown): value is Record<string, unknown> {
return Boolean(value) && typeof value === "object" && !Array.isArray(value);
}
function emptyCounts(): SeverityCounts {
return { critical: 0, high: 0, moderate: 0, low: 0, info: 0 };
}
export function summarizeDependencyAdvisories(
audit: unknown,
policy: Readonly<Record<string, unknown>>,
exceptions: Readonly<Record<string, unknown>>,
lockfileSha256: string,
now: Date = new Date(),
): DependencyAdvisorySummary {
const counts = { production: emptyCounts(), development: emptyCounts() };
if (!isRecord(audit) || !isRecord(audit["advisories"]) || !isRecord(audit["metadata"])) {
return {
status: "UNVERIFIED",
reason: "pnpm audit returned no advisory report (network or registry unavailable)",
counts,
blocking: [],
advisories: [],
};
}
const advisories = Object.values(audit["advisories"]).filter(isRecord).map((advisory) => {
const findings = Array.isArray(advisory["findings"]) ? advisory["findings"].filter(isRecord) : [];
return {
id: String(advisory["github_advisory_id"] ?? advisory["id"] ?? "unknown"),
packageName: String(advisory["module_name"] ?? "unknown"),
versions: findings.map((finding) => String(finding["version"] ?? "unknown")),
severity: String(advisory["severity"] ?? "unknown").toLowerCase(),
// A package reached only through development dependencies never ships.
development: findings.length > 0 && findings.every((finding) => finding["dev"] === true),
patchedVersions: String(advisory["patched_versions"] ?? ""),
};
});
for (const advisory of advisories) {
const scope = advisory.development ? counts.development : counts.production;
if ((SEVERITIES as readonly string[]).includes(advisory.severity)) scope[advisory.severity as Severity] += 1;
}
const verdict = validateVulnerabilityReport(
{
provider: "pnpm-audit (local, not the promotion provider)",
scannedLockfileSha256: lockfileSha256,
findings: advisories.flatMap((advisory) =>
advisory.versions.map((version) => ({
id: advisory.id,
packageName: advisory.packageName,
version,
severity: advisory.severity,
})),
),
},
policy,
exceptions,
lockfileSha256,
now,
);
return {
status: verdict.blocking.length > 0 ? "POLICY_VIOLATION" : "PASS",
reason: null,
counts,
blocking: verdict.blocking,
advisories,
};
}
+103 -2
View File
@@ -1,7 +1,10 @@
import { isIP } from "node:net";
import path from "node:path";
import { connect } from "node:tls";
import type { InstalledServiceWorkerSelection } from "../../src/contracts/service-worker.ts";
import { CACHEABLE_ASSET_CONTENT_TYPES } from "../../src/contracts/service-worker-static-manifest.ts";
import { changedRuntimeConfigBuildFields } from "./runtime-config-switches.ts";
const LOOPBACK_IPV4 = /^127(?:\.\d{1,3}){3}$/;
@@ -42,6 +45,49 @@ export type ProbeResult = Readonly<{
export type ResponseHeaders = Record<string, Record<string, string>>;
export type HostingFetcher = (url: URL) => Promise<Response>;
export type ReleaseIdentity = Readonly<{ buildId: string; releaseId: string }>;
/** The promoted candidate: its manifest names and the texts of its dist/config.json and dist/index.html. */
export type CandidateRelease = ReleaseIdentity & Readonly<{ runtimeConfig: string; indexHtml: string }>;
export type ProbeTransport = Readonly<{
fetcher?: HostingFetcher;
/** The ALPN protocol the host negotiates over TLS, or null when none. */
negotiateAlpn?: (base: URL) => Promise<string | null>;
/** Accepted protocols (`transport.alpnProtocols` in config/hosting/cache-policy.json); empty skips the check. */
alpnProtocols?: readonly string[];
}>;
/**
* 1103/13-02. Node's fetch speaks HTTP/1.1 even to a host that offers h2, so
* the protocol a browser gets is read from the TLS handshake instead: the
* client offers h2 and http/1.1 and the host picks one. The certificate is
* verified as fetch verifies it.
*/
export function negotiatedAlpnProtocol(base: URL, timeoutMs = 10_000): Promise<string | null> {
return new Promise((resolve, reject) => {
const host = base.hostname.replace(/^\[|\]$/gu, "");
const socket = connect({
host,
port: Number(base.port || 443),
...(isIP(host) === 0 ? { servername: host } : {}),
ALPNProtocols: ["h2", "http/1.1"],
});
socket.setTimeout(timeoutMs, () => socket.destroy(new Error("TLS handshake timed out")));
socket.once("secureConnect", () => {
const protocol = socket.alpnProtocol;
socket.end();
resolve(typeof protocol === "string" ? protocol : null);
});
socket.once("error", reject);
});
}
function parsedJsonObject(text: string | null): object | null {
try {
const value: unknown = JSON.parse(text ?? "");
return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
} catch {
return null;
}
}
/** `buildId` and `releaseId` of a release-manifest.json text, or null. */
export function releaseIdentity(manifest: string | null): ReleaseIdentity | null {
@@ -67,13 +113,24 @@ export function releaseIdentity(manifest: string | null): ReleaseIdentity | null
*
* 1101/13-01. The served release manifest must name the candidate's build and
* release. Correct headers on an earlier release are not evidence for this one.
*
* 1103/13-01. Those names come from the CI run, so a release rebuilt in the
* same run (say with the local profile) carries them too. The served
* config.json must equal the candidate's, the one release admission
* (FE-GATE-027) admitted, except for the two emergency switches FE-RB-001 may
* change; and the served index.html must name the candidate's entry script.
*
* 1103/13-02. The host must negotiate a declared protocol (HTTP/2): the
* template splits its initial chunks on that premise.
*/
export async function probeLiveRelease(
base: URL,
paths: Readonly<Record<string, string>>,
candidate: ReleaseIdentity,
fetcher: HostingFetcher = (url) => fetch(url, { redirect: "follow" }),
candidate: CandidateRelease,
transport: ProbeTransport = {},
): Promise<{ responses: ResponseHeaders; results: ProbeResult[] }> {
const fetcher = transport.fetcher ?? ((url: URL) => fetch(url, { redirect: "follow" }));
const negotiateAlpn = transport.negotiateAlpn ?? negotiatedAlpnProtocol;
const responses: ResponseHeaders = {};
const results: ProbeResult[] = [];
const probe = async (surface: string, pathname: string): Promise<string | null> => {
@@ -148,6 +205,50 @@ export async function probeLiveRelease(
passed: entryScript !== null && observed === entryScript,
});
}
const candidateEntryScript = servedEntryScript(candidate.indexHtml);
results.push({
surface: "index",
header: "candidate-entry-script",
expected: candidateEntryScript,
observed: entryScript,
passed: candidateEntryScript !== null && entryScript === candidateEntryScript,
});
if ("runtimeConfig" in paths) {
const served = parsedJsonObject(bodies["runtimeConfig"] ?? null);
const admitted = parsedJsonObject(candidate.runtimeConfig);
const changed = served && admitted ? changedRuntimeConfigBuildFields(admitted, served) : null;
results.push({
surface: "runtimeConfig",
header: "build-fields",
expected: [],
observed: changed ?? "unreadable",
...(changed === null
? { reason: "the served or the candidate config.json is not a JSON object" }
: changed.length > 0
? { reason: "differs from the candidate's config.json beyond the emergency switches" }
: {}),
passed: changed !== null && changed.length === 0,
});
}
const alpnProtocols = transport.alpnProtocols ?? [];
if (alpnProtocols.length > 0) {
let observed: string | null;
try {
observed = await negotiateAlpn(base);
} catch (error: unknown) {
observed = error instanceof Error ? error.name : "UnknownError";
}
results.push({
surface: "transport",
header: "alpn",
expected: alpnProtocols,
observed,
...(observed !== null && alpnProtocols.includes(observed)
? {}
: { reason: "the split initial chunks assume HTTP/2 (docs/architecture/static-delivery.md)" }),
passed: observed !== null && alpnProtocols.includes(observed),
});
}
return { responses, results };
}
+1 -1
View File
@@ -127,7 +127,7 @@ export async function measureOptionalRecipeBundle(input: Readonly<{
copyPublicDir: false,
cssCodeSplit: false,
reportCompressedSize: false,
rollupOptions: {
rolldownOptions: {
input: virtualEntry,
// Budget the complete selected runtime, including internal fail-closed
// guards that a synthetic consumer cannot predict it will exercise.
+37 -1
View File
@@ -1,10 +1,18 @@
export type BundleMeasurements = Readonly<{
initialJsGzipBytes: number;
initialJsFiles: number;
lazyChunks: readonly Readonly<{ path: string; gzipBytes: number }>[];
}>;
/**
* 1103/15-05. `initialJsFiles` bounds the number of initial JavaScript files
* (entry included). The entry preloads them in parallel, which costs no round
* trip over HTTP/2 and queues them six at a time over HTTP/1.1
* (docs/operations/performance-evidence.md, "초기 청크 수와 HTTP/1.1").
*/
export type BundleThresholds = Readonly<{
initialJsGzipBytes: number;
initialJsFiles: number;
lazyChunkGzipBytes: number;
}>;
@@ -14,6 +22,7 @@ export function evaluateBundleBudget(
) {
const initialPassed =
measurements.initialJsGzipBytes <= thresholds.initialJsGzipBytes;
const initialFilesPassed = measurements.initialJsFiles <= thresholds.initialJsFiles;
const lazyResults = measurements.lazyChunks.map((chunk) => ({
...chunk,
threshold: thresholds.lazyChunkGzipBytes,
@@ -21,11 +30,38 @@ export function evaluateBundleBudget(
}));
return Object.freeze({
initialPassed,
initialFilesPassed,
lazyResults: Object.freeze(lazyResults),
passed: initialPassed && lazyResults.every((chunk) => chunk.passed),
passed: initialPassed && initialFilesPassed && lazyResults.every((chunk) => chunk.passed),
});
}
/**
* 1103/15-03. One line per exceeded limit with the measured value, the limit
* and the excess, so a failed check:bundle says what to cut without opening
* artifacts/performance/bundle.json.
*/
export function describeBundleBudgetFailures(
measurements: BundleMeasurements,
thresholds: BundleThresholds,
): string[] {
const over = (label: string, measured: number, limit: number, unit = " gzip bytes") =>
`${label} ${measured}${unit} > budget ${limit} (over by ${measured - limit})`;
const lines: string[] = [];
if (measurements.initialJsGzipBytes > thresholds.initialJsGzipBytes) {
lines.push(over("initial JavaScript", measurements.initialJsGzipBytes, thresholds.initialJsGzipBytes));
}
if (measurements.initialJsFiles > thresholds.initialJsFiles) {
lines.push(over("initial JavaScript files", measurements.initialJsFiles, thresholds.initialJsFiles, ""));
}
for (const chunk of measurements.lazyChunks) {
if (chunk.gzipBytes > thresholds.lazyChunkGzipBytes) {
lines.push(over(`lazy chunk ${chunk.path}`, chunk.gzipBytes, thresholds.lazyChunkGzipBytes));
}
}
return lines;
}
export type LabMetrics = Readonly<{
lcpMs: number;
cls: number;
+27
View File
@@ -0,0 +1,27 @@
/**
* 1101/13-05. The only fields an operator may change in a deployed config.json
* without a rebuild (docs/runbooks/FE-RB-001.md). Every other field belongs to
* the build: BUILD_ID and RELEASE_ID must still match the deployed HTML and
* release manifest, or every boot stops with CONFIG_BUILD_MISMATCH.
*
* 1103/13-01. The live hosting probe (FE-GATE-019) compares the served
* config.json with the promoted candidate's by the same rule, so the release
* admission and the probe agree on what an edited document may change.
*/
export const RUNTIME_CONFIG_EMERGENCY_SWITCHES: ReadonlySet<string> = new Set([
"CAPABILITY_OVERRIDES",
"FEATURE_OVERRIDES",
]);
/** Fields other than the emergency switches whose values differ, sorted. */
export function changedRuntimeConfigBuildFields(original: object, edited: object): string[] {
const before = new Map(Object.entries(original));
const after = new Map(Object.entries(edited));
return [...new Set([...before.keys(), ...after.keys()])]
.filter(
(field) =>
!RUNTIME_CONFIG_EMERGENCY_SWITCHES.has(field) &&
JSON.stringify(before.get(field)) !== JSON.stringify(after.get(field)),
)
.sort();
}