Compare commits
2
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 donghyeon-ka
|
6b4b956d51 | ||
|
donghyeon-ka
|
a2a97ebcc7 |
@@ -1,189 +0,0 @@
|
|||||||
name: frontend-quality-gates
|
|
||||||
|
|
||||||
on:
|
|
||||||
push:
|
|
||||||
branches: [develop]
|
|
||||||
tags: ["v*"]
|
|
||||||
pull_request:
|
|
||||||
workflow_dispatch:
|
|
||||||
inputs:
|
|
||||||
stage:
|
|
||||||
description: Highest promotion tier to evaluate
|
|
||||||
required: true
|
|
||||||
default: merge
|
|
||||||
type: choice
|
|
||||||
options:
|
|
||||||
- merge
|
|
||||||
- release
|
|
||||||
- production
|
|
||||||
- field
|
|
||||||
- documentation
|
|
||||||
|
|
||||||
env:
|
|
||||||
NODE_VERSION: "24"
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
merge_gate:
|
|
||||||
name: ${{ matrix.gate }} / ${{ matrix.name }}
|
|
||||||
if: ${{ gitea.event_name != 'workflow_dispatch' || inputs.stage != 'documentation' }}
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
strategy:
|
|
||||||
fail-fast: false
|
|
||||||
matrix:
|
|
||||||
include:
|
|
||||||
- { gate: FE-GATE-001, name: manifest-lockfile, browser: false }
|
|
||||||
- { gate: FE-GATE-002, name: lint, browser: false }
|
|
||||||
- { gate: FE-GATE-003, name: typecheck, browser: false }
|
|
||||||
- { gate: FE-GATE-004, name: runtime-schema, browser: false }
|
|
||||||
- { gate: FE-GATE-005, name: unit, browser: false }
|
|
||||||
- { gate: FE-GATE-006, name: component, browser: false }
|
|
||||||
- { gate: FE-GATE-007, name: integration, browser: false }
|
|
||||||
- { gate: FE-GATE-008, name: e2e, browser: true }
|
|
||||||
- { gate: FE-GATE-009, name: accessibility, browser: true }
|
|
||||||
- { gate: FE-GATE-010, name: architecture, browser: false }
|
|
||||||
- { gate: FE-GATE-011, name: build, browser: false }
|
|
||||||
- { gate: FE-GATE-013, name: security, browser: false }
|
|
||||||
- { gate: FE-GATE-020, name: sample-removal, browser: false }
|
|
||||||
steps:
|
|
||||||
- uses: actions/checkout@v4
|
|
||||||
- uses: actions/setup-node@v4
|
|
||||||
with:
|
|
||||||
node-version: ${{ env.NODE_VERSION }}
|
|
||||||
- name: Frozen install
|
|
||||||
run: |
|
|
||||||
corepack enable
|
|
||||||
corepack pnpm install --frozen-lockfile
|
|
||||||
- name: Install Chromium
|
|
||||||
if: ${{ matrix.browser }}
|
|
||||||
run: corepack pnpm exec playwright install --with-deps chromium
|
|
||||||
- name: Run blocking gate
|
|
||||||
run: corepack pnpm ci:gate -- ${{ matrix.gate }}
|
|
||||||
- name: Upload gate evidence
|
|
||||||
if: always()
|
|
||||||
uses: actions/upload-artifact@v4
|
|
||||||
with:
|
|
||||||
name: ${{ matrix.gate }}-${{ gitea.run_id }}
|
|
||||||
path: artifacts/
|
|
||||||
if-no-files-found: warn
|
|
||||||
|
|
||||||
release_gate:
|
|
||||||
name: ${{ matrix.gate }} / ${{ matrix.name }}
|
|
||||||
needs: merge_gate
|
|
||||||
if: ${{ startsWith(gitea.ref, 'refs/tags/v') || (gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'release' || inputs.stage == 'production' || inputs.stage == 'field')) }}
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
env:
|
|
||||||
HOSTING_BASE_URL: ${{ vars.HOSTING_BASE_URL }}
|
|
||||||
strategy:
|
|
||||||
fail-fast: false
|
|
||||||
matrix:
|
|
||||||
include:
|
|
||||||
- { gate: FE-GATE-012, name: bundle, browser: false }
|
|
||||||
- { gate: FE-GATE-014, name: config-compatibility, browser: false }
|
|
||||||
- { gate: FE-GATE-015, name: release-coherence, browser: false }
|
|
||||||
- { gate: FE-GATE-019, name: hosting-header, browser: false }
|
|
||||||
- { gate: FE-GATE-026, name: lab-performance, browser: true }
|
|
||||||
steps:
|
|
||||||
- uses: actions/checkout@v4
|
|
||||||
- uses: actions/setup-node@v4
|
|
||||||
with:
|
|
||||||
node-version: ${{ env.NODE_VERSION }}
|
|
||||||
- name: Frozen install
|
|
||||||
run: |
|
|
||||||
corepack enable
|
|
||||||
corepack pnpm install --frozen-lockfile
|
|
||||||
- name: Install Chromium
|
|
||||||
if: ${{ matrix.browser }}
|
|
||||||
run: corepack pnpm exec playwright install --with-deps chromium
|
|
||||||
- name: Run blocking gate
|
|
||||||
run: corepack pnpm ci:gate -- ${{ matrix.gate }}
|
|
||||||
- name: Upload gate evidence
|
|
||||||
if: always()
|
|
||||||
uses: actions/upload-artifact@v4
|
|
||||||
with:
|
|
||||||
name: ${{ matrix.gate }}-${{ gitea.run_id }}
|
|
||||||
path: artifacts/
|
|
||||||
if-no-files-found: warn
|
|
||||||
|
|
||||||
production_gate:
|
|
||||||
name: ${{ matrix.gate }} / ${{ matrix.name }}
|
|
||||||
needs: release_gate
|
|
||||||
if: ${{ gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'production' || inputs.stage == 'field') }}
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
strategy:
|
|
||||||
fail-fast: false
|
|
||||||
matrix:
|
|
||||||
include:
|
|
||||||
- { gate: FE-GATE-016, name: rollback-drill }
|
|
||||||
- { gate: FE-GATE-021, name: runbook-boot-config }
|
|
||||||
- { gate: FE-GATE-022, name: runbook-chunk-mismatch }
|
|
||||||
- { gate: FE-GATE-023, name: runbook-api-degradation }
|
|
||||||
- { gate: FE-GATE-024, name: runbook-telemetry }
|
|
||||||
- { gate: FE-GATE-025, name: runbook-release-rollback }
|
|
||||||
steps:
|
|
||||||
- uses: actions/checkout@v4
|
|
||||||
- uses: actions/setup-node@v4
|
|
||||||
with:
|
|
||||||
node-version: ${{ env.NODE_VERSION }}
|
|
||||||
- name: Frozen install
|
|
||||||
run: |
|
|
||||||
corepack enable
|
|
||||||
corepack pnpm install --frozen-lockfile
|
|
||||||
- name: Run blocking gate
|
|
||||||
run: corepack pnpm ci:gate -- ${{ matrix.gate }}
|
|
||||||
- name: Upload gate evidence
|
|
||||||
if: always()
|
|
||||||
uses: actions/upload-artifact@v4
|
|
||||||
with:
|
|
||||||
name: ${{ matrix.gate }}-${{ gitea.run_id }}
|
|
||||||
path: artifacts/
|
|
||||||
if-no-files-found: warn
|
|
||||||
|
|
||||||
field_gate:
|
|
||||||
name: FE-GATE-018 / field-web-vitals
|
|
||||||
needs: production_gate
|
|
||||||
if: ${{ gitea.event_name == 'workflow_dispatch' && inputs.stage == 'field' }}
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
env:
|
|
||||||
FIELD_WEB_VITALS_INPUT: ${{ vars.FIELD_WEB_VITALS_INPUT }}
|
|
||||||
MIN_ELIGIBLE_SAMPLES: ${{ vars.MIN_ELIGIBLE_SAMPLES }}
|
|
||||||
steps:
|
|
||||||
- uses: actions/checkout@v4
|
|
||||||
- uses: actions/setup-node@v4
|
|
||||||
with:
|
|
||||||
node-version: ${{ env.NODE_VERSION }}
|
|
||||||
- name: Frozen install
|
|
||||||
run: |
|
|
||||||
corepack enable
|
|
||||||
corepack pnpm install --frozen-lockfile
|
|
||||||
- name: Run blocking gate
|
|
||||||
run: corepack pnpm ci:gate -- FE-GATE-018
|
|
||||||
- name: Upload gate evidence
|
|
||||||
if: always()
|
|
||||||
uses: actions/upload-artifact@v4
|
|
||||||
with:
|
|
||||||
name: FE-GATE-018-${{ gitea.run_id }}
|
|
||||||
path: artifacts/
|
|
||||||
if-no-files-found: warn
|
|
||||||
|
|
||||||
documentation_gate:
|
|
||||||
name: FE-GATE-017 / diagram-review
|
|
||||||
if: ${{ gitea.event_name == 'workflow_dispatch' && inputs.stage == 'documentation' }}
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
steps:
|
|
||||||
- uses: actions/checkout@v4
|
|
||||||
- uses: actions/setup-node@v4
|
|
||||||
with:
|
|
||||||
node-version: ${{ env.NODE_VERSION }}
|
|
||||||
- name: Frozen install
|
|
||||||
run: |
|
|
||||||
corepack enable
|
|
||||||
corepack pnpm install --frozen-lockfile
|
|
||||||
- name: Run documentation gate
|
|
||||||
run: corepack pnpm ci:gate -- FE-GATE-017
|
|
||||||
- name: Upload gate evidence
|
|
||||||
if: always()
|
|
||||||
uses: actions/upload-artifact@v4
|
|
||||||
with:
|
|
||||||
name: FE-GATE-017-${{ gitea.run_id }}
|
|
||||||
path: artifacts/
|
|
||||||
if-no-files-found: warn
|
|
||||||
@@ -1,77 +1,2 @@
|
|||||||
# Clean Architecture Frontend Template
|
# clean-architecture-frontend-template
|
||||||
|
|
||||||
A React/Vite reference implementation where architecture boundaries,
|
|
||||||
integration behavior, release coherence, accessibility, performance, and
|
|
||||||
operations are executable contracts rather than conventions.
|
|
||||||
|
|
||||||
## Start locally
|
|
||||||
|
|
||||||
Requirements: Node 24 and Corepack. The repository pins pnpm in `package.json`.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
corepack pnpm install --frozen-lockfile
|
|
||||||
corepack pnpm dev
|
|
||||||
```
|
|
||||||
|
|
||||||
Runtime-public settings live in `public/config.json` and are validated before
|
|
||||||
the product tree mounts. Client secrets are forbidden.
|
|
||||||
|
|
||||||
## Architecture
|
|
||||||
|
|
||||||
Dependencies point inward:
|
|
||||||
|
|
||||||
```text
|
|
||||||
presentation -> application -> domain
|
|
||||||
adapters -----^
|
|
||||||
bootstrap composes concrete adapters
|
|
||||||
contracts own cross-cutting registries
|
|
||||||
```
|
|
||||||
|
|
||||||
See `docs/architecture/overview.md` and `docs/architecture/layers.md`. The
|
|
||||||
removable sample slice is under `src/sample/contract-fixture`; product code is
|
|
||||||
not allowed to import it.
|
|
||||||
|
|
||||||
## Verification
|
|
||||||
|
|
||||||
Common local checks:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
corepack pnpm lint
|
|
||||||
corepack pnpm check:types
|
|
||||||
corepack pnpm check:architecture
|
|
||||||
corepack pnpm test:all
|
|
||||||
corepack pnpm test:e2e
|
|
||||||
corepack pnpm test:a11y
|
|
||||||
corepack pnpm build
|
|
||||||
corepack pnpm check:bundle
|
|
||||||
corepack pnpm test:performance
|
|
||||||
corepack pnpm verify:compatibility
|
|
||||||
corepack pnpm verify:release
|
|
||||||
corepack pnpm check:registries
|
|
||||||
corepack pnpm drill:runbooks
|
|
||||||
corepack pnpm check:ci
|
|
||||||
```
|
|
||||||
|
|
||||||
Two gates intentionally need external evidence:
|
|
||||||
|
|
||||||
- `review:a11y-manual` needs a signed human keyboard/focus/screen-reader review.
|
|
||||||
- `collect:web-vitals-evidence` stays `FAIL_UNVERIFIED` until a reviewed minimum
|
|
||||||
eligible-sample threshold and 28 days of production data exist.
|
|
||||||
|
|
||||||
Live release verification additionally requires `HOSTING_BASE_URL`.
|
|
||||||
|
|
||||||
## CI and evidence
|
|
||||||
|
|
||||||
The 26-gate registry is `config/ci/gates.json`; the Gitea workflow is
|
|
||||||
`.gitea/workflows/quality-gates.yml`. It follows:
|
|
||||||
|
|
||||||
```text
|
|
||||||
MERGE_READY -> RELEASE_READY -> PROD_PROMOTION_READY -> FIELD_SLO_READY
|
|
||||||
```
|
|
||||||
|
|
||||||
`DOCUMENTATION_READY` is independent. No gate is downgraded to a warning.
|
|
||||||
Machine-readable evidence is written below `artifacts/`; generated evidence is
|
|
||||||
ignored by Git while `.gitkeep` files preserve the taxonomy.
|
|
||||||
|
|
||||||
Operational details are in `docs/operations/`, with incident procedures in
|
|
||||||
`docs/runbooks/`.
|
|
||||||
|
|||||||
@@ -1,342 +0,0 @@
|
|||||||
{
|
|
||||||
"schemaVersion": 1,
|
|
||||||
"providerAdapter": ".gitea/workflows/quality-gates.yml",
|
|
||||||
"stages": {
|
|
||||||
"merge": {
|
|
||||||
"readiness": "MERGE_READY",
|
|
||||||
"needs": null,
|
|
||||||
"gates": [
|
|
||||||
"FE-GATE-001",
|
|
||||||
"FE-GATE-002",
|
|
||||||
"FE-GATE-003",
|
|
||||||
"FE-GATE-004",
|
|
||||||
"FE-GATE-005",
|
|
||||||
"FE-GATE-006",
|
|
||||||
"FE-GATE-007",
|
|
||||||
"FE-GATE-008",
|
|
||||||
"FE-GATE-009",
|
|
||||||
"FE-GATE-010",
|
|
||||||
"FE-GATE-011",
|
|
||||||
"FE-GATE-013",
|
|
||||||
"FE-GATE-020"
|
|
||||||
]
|
|
||||||
},
|
|
||||||
"release": {
|
|
||||||
"readiness": "RELEASE_READY",
|
|
||||||
"needs": "merge",
|
|
||||||
"gates": [
|
|
||||||
"FE-GATE-012",
|
|
||||||
"FE-GATE-014",
|
|
||||||
"FE-GATE-015",
|
|
||||||
"FE-GATE-019",
|
|
||||||
"FE-GATE-026"
|
|
||||||
]
|
|
||||||
},
|
|
||||||
"production": {
|
|
||||||
"readiness": "PROD_PROMOTION_READY",
|
|
||||||
"needs": "release",
|
|
||||||
"gates": [
|
|
||||||
"FE-GATE-016",
|
|
||||||
"FE-GATE-021",
|
|
||||||
"FE-GATE-022",
|
|
||||||
"FE-GATE-023",
|
|
||||||
"FE-GATE-024",
|
|
||||||
"FE-GATE-025"
|
|
||||||
]
|
|
||||||
},
|
|
||||||
"field": {
|
|
||||||
"readiness": "FIELD_SLO_READY",
|
|
||||||
"needs": "production",
|
|
||||||
"gates": ["FE-GATE-018"]
|
|
||||||
},
|
|
||||||
"documentation": {
|
|
||||||
"readiness": "DOCUMENTATION_READY",
|
|
||||||
"needs": null,
|
|
||||||
"gates": ["FE-GATE-017"]
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"gates": {
|
|
||||||
"FE-GATE-001": {
|
|
||||||
"name": "manifest-lockfile",
|
|
||||||
"steps": [{ "script": "verify:lockfile", "expect": "pass" }],
|
|
||||||
"logPath": "artifacts/quality/install.txt",
|
|
||||||
"evidence": ["artifacts/quality/install.txt"],
|
|
||||||
"retentionClass": "merge-cycle"
|
|
||||||
},
|
|
||||||
"FE-GATE-002": {
|
|
||||||
"name": "lint",
|
|
||||||
"steps": [{ "script": "lint", "expect": "pass" }],
|
|
||||||
"logPath": "artifacts/quality/lint.txt",
|
|
||||||
"evidence": ["artifacts/quality/lint.txt"],
|
|
||||||
"retentionClass": "merge-cycle"
|
|
||||||
},
|
|
||||||
"FE-GATE-003": {
|
|
||||||
"name": "typecheck",
|
|
||||||
"steps": [
|
|
||||||
{ "script": "check:types", "expect": "pass" },
|
|
||||||
{ "script": "check:types:fixture", "expect": "fail" }
|
|
||||||
],
|
|
||||||
"logPath": "artifacts/quality/check-types.txt",
|
|
||||||
"evidence": ["artifacts/quality/check-types.txt"],
|
|
||||||
"retentionClass": "merge-cycle"
|
|
||||||
},
|
|
||||||
"FE-GATE-004": {
|
|
||||||
"name": "runtime-schema",
|
|
||||||
"steps": [{ "script": "test:runtime-schema", "expect": "pass" }],
|
|
||||||
"logPath": "artifacts/quality/gates/FE-GATE-004.txt",
|
|
||||||
"evidence": ["artifacts/tests/runtime-schema.xml"],
|
|
||||||
"retentionClass": "merge-cycle"
|
|
||||||
},
|
|
||||||
"FE-GATE-005": {
|
|
||||||
"name": "unit",
|
|
||||||
"steps": [{ "script": "test:unit", "expect": "pass" }],
|
|
||||||
"logPath": "artifacts/quality/gates/FE-GATE-005.txt",
|
|
||||||
"evidence": ["artifacts/tests/unit.xml"],
|
|
||||||
"retentionClass": "merge-cycle"
|
|
||||||
},
|
|
||||||
"FE-GATE-006": {
|
|
||||||
"name": "component",
|
|
||||||
"steps": [{ "script": "test:component", "expect": "pass" }],
|
|
||||||
"logPath": "artifacts/quality/gates/FE-GATE-006.txt",
|
|
||||||
"evidence": ["artifacts/tests/component.xml"],
|
|
||||||
"retentionClass": "merge-cycle"
|
|
||||||
},
|
|
||||||
"FE-GATE-007": {
|
|
||||||
"name": "integration",
|
|
||||||
"steps": [{ "script": "test:integration", "expect": "pass" }],
|
|
||||||
"logPath": "artifacts/quality/gates/FE-GATE-007.txt",
|
|
||||||
"evidence": ["artifacts/tests/integration.xml"],
|
|
||||||
"retentionClass": "merge-cycle"
|
|
||||||
},
|
|
||||||
"FE-GATE-008": {
|
|
||||||
"name": "e2e",
|
|
||||||
"steps": [{ "script": "test:e2e", "expect": "pass" }],
|
|
||||||
"logPath": "artifacts/quality/gates/FE-GATE-008.txt",
|
|
||||||
"evidence": ["artifacts/tests/e2e/report/index.html"],
|
|
||||||
"retentionClass": "merge-cycle"
|
|
||||||
},
|
|
||||||
"FE-GATE-009": {
|
|
||||||
"name": "accessibility",
|
|
||||||
"steps": [
|
|
||||||
{ "script": "test:a11y", "expect": "pass" },
|
|
||||||
{ "script": "review:a11y-manual", "expect": "pass" }
|
|
||||||
],
|
|
||||||
"logPath": "artifacts/quality/gates/FE-GATE-009.txt",
|
|
||||||
"evidence": [
|
|
||||||
"artifacts/tests/a11y.json",
|
|
||||||
"artifacts/tests/a11y-manual/APP_HOME.md",
|
|
||||||
"artifacts/tests/a11y-manual/SAMPLE_RESOURCE_LIST.md",
|
|
||||||
"artifacts/tests/a11y-manual/NOT_FOUND.md",
|
|
||||||
"artifacts/tests/a11y-manual/report.json"
|
|
||||||
],
|
|
||||||
"retentionClass": "merge-cycle"
|
|
||||||
},
|
|
||||||
"FE-GATE-010": {
|
|
||||||
"name": "architecture",
|
|
||||||
"steps": [{ "script": "check:architecture", "expect": "pass" }],
|
|
||||||
"logPath": "artifacts/quality/gates/FE-GATE-010.txt",
|
|
||||||
"evidence": ["artifacts/quality/dependency-report.json"],
|
|
||||||
"retentionClass": "merge-cycle"
|
|
||||||
},
|
|
||||||
"FE-GATE-011": {
|
|
||||||
"name": "build",
|
|
||||||
"steps": [{ "script": "build", "expect": "pass" }],
|
|
||||||
"logPath": "artifacts/quality/gates/FE-GATE-011.txt",
|
|
||||||
"evidence": ["artifacts/release/build-manifest.json"],
|
|
||||||
"retentionClass": "release-coherence"
|
|
||||||
},
|
|
||||||
"FE-GATE-012": {
|
|
||||||
"name": "bundle",
|
|
||||||
"steps": [
|
|
||||||
{ "script": "build", "expect": "pass" },
|
|
||||||
{ "script": "check:bundle", "expect": "pass" }
|
|
||||||
],
|
|
||||||
"logPath": "artifacts/quality/gates/FE-GATE-012.txt",
|
|
||||||
"evidence": ["artifacts/performance/bundle.json"],
|
|
||||||
"retentionClass": "release-coherence"
|
|
||||||
},
|
|
||||||
"FE-GATE-013": {
|
|
||||||
"name": "security",
|
|
||||||
"steps": [
|
|
||||||
{ "script": "build:release", "expect": "pass" },
|
|
||||||
{ "script": "check:browser-security", "expect": "pass" }
|
|
||||||
],
|
|
||||||
"logPath": "artifacts/quality/gates/FE-GATE-013.txt",
|
|
||||||
"evidence": [
|
|
||||||
"artifacts/security/scan.sarif",
|
|
||||||
"artifacts/release/dependency-inventory.json",
|
|
||||||
"artifacts/security/dependency-diff.json"
|
|
||||||
],
|
|
||||||
"retentionClass": "release-coherence"
|
|
||||||
},
|
|
||||||
"FE-GATE-014": {
|
|
||||||
"name": "config-compatibility",
|
|
||||||
"steps": [{ "script": "verify:compatibility", "expect": "pass" }],
|
|
||||||
"logPath": "artifacts/quality/gates/FE-GATE-014.txt",
|
|
||||||
"evidence": ["artifacts/release/compatibility.json"],
|
|
||||||
"retentionClass": "release-coherence"
|
|
||||||
},
|
|
||||||
"FE-GATE-015": {
|
|
||||||
"name": "release-coherence",
|
|
||||||
"steps": [
|
|
||||||
{ "script": "build", "expect": "pass" },
|
|
||||||
{ "script": "verify:release", "expect": "pass" }
|
|
||||||
],
|
|
||||||
"logPath": "artifacts/quality/gates/FE-GATE-015.txt",
|
|
||||||
"evidence": ["artifacts/release/verification.json"],
|
|
||||||
"retentionClass": "release-coherence"
|
|
||||||
},
|
|
||||||
"FE-GATE-016": {
|
|
||||||
"name": "rollback-drill",
|
|
||||||
"steps": [
|
|
||||||
{ "script": "build", "expect": "pass" },
|
|
||||||
{
|
|
||||||
"script": "drill:runbook",
|
|
||||||
"args": ["--", "FE-RB-005"],
|
|
||||||
"expect": "pass"
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"logPath": "artifacts/quality/gates/FE-GATE-016.txt",
|
|
||||||
"evidence": [
|
|
||||||
"artifacts/runbooks/FE-RB-005/local-release/record.json"
|
|
||||||
],
|
|
||||||
"retentionClass": "prod-drill"
|
|
||||||
},
|
|
||||||
"FE-GATE-017": {
|
|
||||||
"name": "diagram-review",
|
|
||||||
"steps": [{ "script": "verify:documentation", "expect": "pass" }],
|
|
||||||
"logPath": "artifacts/quality/gates/FE-GATE-017.txt",
|
|
||||||
"evidence": ["artifacts/quality/documentation-review.json"],
|
|
||||||
"retentionClass": "documentation"
|
|
||||||
},
|
|
||||||
"FE-GATE-018": {
|
|
||||||
"name": "field-web-vitals",
|
|
||||||
"requiresEnvironment": [
|
|
||||||
"FIELD_WEB_VITALS_INPUT",
|
|
||||||
"MIN_ELIGIBLE_SAMPLES"
|
|
||||||
],
|
|
||||||
"steps": [
|
|
||||||
{ "script": "collect:web-vitals-evidence", "expect": "pass" }
|
|
||||||
],
|
|
||||||
"logPath": "artifacts/quality/gates/FE-GATE-018.txt",
|
|
||||||
"evidence": ["artifacts/performance/field-web-vitals.json"],
|
|
||||||
"retentionClass": "field"
|
|
||||||
},
|
|
||||||
"FE-GATE-019": {
|
|
||||||
"name": "hosting-header",
|
|
||||||
"requiresEnvironment": ["HOSTING_BASE_URL"],
|
|
||||||
"steps": [
|
|
||||||
{ "script": "build", "expect": "pass" },
|
|
||||||
{ "script": "verify:hosting-headers", "expect": "pass" }
|
|
||||||
],
|
|
||||||
"logPath": "artifacts/quality/gates/FE-GATE-019.txt",
|
|
||||||
"evidence": ["artifacts/release/hosting-headers.json"],
|
|
||||||
"retentionClass": "release-coherence"
|
|
||||||
},
|
|
||||||
"FE-GATE-020": {
|
|
||||||
"name": "sample-removal",
|
|
||||||
"steps": [{ "script": "test:sample-removal", "expect": "pass" }],
|
|
||||||
"logPath": "artifacts/quality/gates/FE-GATE-020.txt",
|
|
||||||
"evidence": ["artifacts/tests/sample-removal.xml"],
|
|
||||||
"retentionClass": "merge-cycle"
|
|
||||||
},
|
|
||||||
"FE-GATE-021": {
|
|
||||||
"name": "runbook-boot-config",
|
|
||||||
"steps": [
|
|
||||||
{ "script": "build", "expect": "pass" },
|
|
||||||
{
|
|
||||||
"script": "drill:runbook",
|
|
||||||
"args": ["--", "FE-RB-001"],
|
|
||||||
"expect": "pass"
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"logPath": "artifacts/quality/gates/FE-GATE-021.txt",
|
|
||||||
"evidence": [
|
|
||||||
"artifacts/runbooks/FE-RB-001/local-release/record.json"
|
|
||||||
],
|
|
||||||
"retentionClass": "prod-drill"
|
|
||||||
},
|
|
||||||
"FE-GATE-022": {
|
|
||||||
"name": "runbook-chunk-mismatch",
|
|
||||||
"steps": [
|
|
||||||
{ "script": "build", "expect": "pass" },
|
|
||||||
{
|
|
||||||
"script": "drill:runbook",
|
|
||||||
"args": ["--", "FE-RB-002"],
|
|
||||||
"expect": "pass"
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"logPath": "artifacts/quality/gates/FE-GATE-022.txt",
|
|
||||||
"evidence": [
|
|
||||||
"artifacts/runbooks/FE-RB-002/local-release/record.json"
|
|
||||||
],
|
|
||||||
"retentionClass": "prod-drill"
|
|
||||||
},
|
|
||||||
"FE-GATE-023": {
|
|
||||||
"name": "runbook-api-degradation",
|
|
||||||
"steps": [
|
|
||||||
{ "script": "build", "expect": "pass" },
|
|
||||||
{
|
|
||||||
"script": "drill:runbook",
|
|
||||||
"args": ["--", "FE-RB-003"],
|
|
||||||
"expect": "pass"
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"logPath": "artifacts/quality/gates/FE-GATE-023.txt",
|
|
||||||
"evidence": [
|
|
||||||
"artifacts/runbooks/FE-RB-003/local-release/record.json"
|
|
||||||
],
|
|
||||||
"retentionClass": "prod-drill"
|
|
||||||
},
|
|
||||||
"FE-GATE-024": {
|
|
||||||
"name": "runbook-telemetry",
|
|
||||||
"steps": [
|
|
||||||
{ "script": "build", "expect": "pass" },
|
|
||||||
{
|
|
||||||
"script": "drill:runbook",
|
|
||||||
"args": ["--", "FE-RB-004"],
|
|
||||||
"expect": "pass"
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"logPath": "artifacts/quality/gates/FE-GATE-024.txt",
|
|
||||||
"evidence": [
|
|
||||||
"artifacts/runbooks/FE-RB-004/local-release/record.json"
|
|
||||||
],
|
|
||||||
"retentionClass": "prod-drill"
|
|
||||||
},
|
|
||||||
"FE-GATE-025": {
|
|
||||||
"name": "runbook-release-rollback",
|
|
||||||
"steps": [
|
|
||||||
{ "script": "build", "expect": "pass" },
|
|
||||||
{
|
|
||||||
"script": "drill:runbook",
|
|
||||||
"args": ["--", "FE-RB-005"],
|
|
||||||
"expect": "pass"
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"logPath": "artifacts/quality/gates/FE-GATE-025.txt",
|
|
||||||
"evidence": [
|
|
||||||
"artifacts/runbooks/FE-RB-005/local-release/record.json"
|
|
||||||
],
|
|
||||||
"retentionClass": "prod-drill"
|
|
||||||
},
|
|
||||||
"FE-GATE-026": {
|
|
||||||
"name": "lab-performance",
|
|
||||||
"steps": [
|
|
||||||
{ "script": "build", "expect": "pass" },
|
|
||||||
{ "script": "test:performance", "expect": "pass" }
|
|
||||||
],
|
|
||||||
"logPath": "artifacts/quality/gates/FE-GATE-026.txt",
|
|
||||||
"evidence": ["artifacts/performance/lab.json"],
|
|
||||||
"retentionClass": "release-coherence"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"retention": {
|
|
||||||
"durationStatus": "UNSUPPORTED_PENDING_ORGANIZATION_POLICY",
|
|
||||||
"merge-cycle": "at least through pull-request readiness decision",
|
|
||||||
"release-coherence": "at least until the next release is promoted",
|
|
||||||
"prod-drill": "at least until the next production promotion decision",
|
|
||||||
"field": "through the 28-day window and aggregation",
|
|
||||||
"documentation": "through documentation readiness review"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
@@ -1,5 +1,25 @@
|
|||||||
{
|
{
|
||||||
"schemaVersion": 1,
|
"schemaVersion": 1,
|
||||||
"releaseId": "local-release",
|
"releaseId": "local-release",
|
||||||
|
"environment": "replace-with-production",
|
||||||
|
"source": {
|
||||||
|
"system": "",
|
||||||
|
"exportId": ""
|
||||||
|
},
|
||||||
|
"privacy": {
|
||||||
|
"approved": false,
|
||||||
|
"approvalRef": ""
|
||||||
|
},
|
||||||
|
"window": {
|
||||||
|
"start": "2026-06-01T00:00:00Z",
|
||||||
|
"end": "2026-06-29T00:00:00Z"
|
||||||
|
},
|
||||||
|
"thresholdDecision": {
|
||||||
|
"status": "pending",
|
||||||
|
"minimumEligibleSamples": null,
|
||||||
|
"owner": "",
|
||||||
|
"reviewedAt": "",
|
||||||
|
"evidenceRef": ""
|
||||||
|
},
|
||||||
"samples": []
|
"samples": []
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -1,93 +0,0 @@
|
|||||||
{
|
|
||||||
"schemaVersion": 1,
|
|
||||||
"runbooks": {
|
|
||||||
"FE-RB-001": {
|
|
||||||
"title": "Boot configuration failure",
|
|
||||||
"gateId": "FE-GATE-021",
|
|
||||||
"triggerKinds": ["BOOT_CONFIG_FAILURE"],
|
|
||||||
"containment": "stop product route mount, show the safe support shell, and refetch at most once",
|
|
||||||
"window": "owner triage planned-default 5m",
|
|
||||||
"escalation": ["env-config owner", "release owner"],
|
|
||||||
"recoveryEvidence": [
|
|
||||||
"clean-session boot",
|
|
||||||
"product root mount",
|
|
||||||
"config validation",
|
|
||||||
"no repeated boot error"
|
|
||||||
],
|
|
||||||
"negativeFixture": "a valid config followed by an injected mount failure must fail recovery"
|
|
||||||
},
|
|
||||||
"FE-RB-002": {
|
|
||||||
"title": "Chunk, manifest, or deployment mismatch",
|
|
||||||
"gateId": "FE-GATE-022",
|
|
||||||
"triggerKinds": [
|
|
||||||
"CHUNK_LOAD_FAILURE",
|
|
||||||
"RELEASE_MANIFEST_FAILURE",
|
|
||||||
"DEPLOY_MISMATCH"
|
|
||||||
],
|
|
||||||
"containment": "warn for dirty state, fetch manifest no-store once, and allow one guarded reload",
|
|
||||||
"window": "release owner triage planned-default 5m",
|
|
||||||
"escalation": ["release-cache owner", "hosting/CDN owner"],
|
|
||||||
"recoveryEvidence": [
|
|
||||||
"entry and lazy assets reachable",
|
|
||||||
"release tuple coherent",
|
|
||||||
"second reload blocked",
|
|
||||||
"critical route smoke"
|
|
||||||
],
|
|
||||||
"negativeFixture": "a second failure for the same release pair must not reload"
|
|
||||||
},
|
|
||||||
"FE-RB-003": {
|
|
||||||
"title": "Backend API degradation",
|
|
||||||
"gateId": "FE-GATE-023",
|
|
||||||
"triggerKinds": [
|
|
||||||
"TERMINAL_NETWORK_RATE",
|
|
||||||
"REQUEST_TIMEOUT_RATE",
|
|
||||||
"SERVER_FAILURE_RATE",
|
|
||||||
"SCHEMA_MISMATCH"
|
|
||||||
],
|
|
||||||
"containment": "do not expand retry caps, serve safe stale reads, and never retry an unkeyed mutation",
|
|
||||||
"window": "rolling 5m trigger; first classification planned-default 10m",
|
|
||||||
"escalation": [
|
|
||||||
"api-client owner",
|
|
||||||
"backend operation owner",
|
|
||||||
"release compatibility owner"
|
|
||||||
],
|
|
||||||
"recoveryEvidence": [
|
|
||||||
"terminal failure rate at baseline",
|
|
||||||
"no retry amplification",
|
|
||||||
"critical read/write smoke",
|
|
||||||
"schema fixtures"
|
|
||||||
],
|
|
||||||
"negativeFixture": "an unkeyed POST receiving 503 must not retry"
|
|
||||||
},
|
|
||||||
"FE-RB-004": {
|
|
||||||
"title": "Telemetry sink failure",
|
|
||||||
"gateId": "FE-GATE-024",
|
|
||||||
"triggerKinds": ["TELEMETRY_FAILURE"],
|
|
||||||
"containment": "keep product flow available, bound the queue, and never report recursively to the failing sink",
|
|
||||||
"window": "platform triage planned-default 15m",
|
|
||||||
"escalation": ["observability owner", "telemetry platform owner"],
|
|
||||||
"recoveryEvidence": [
|
|
||||||
"product flow unaffected",
|
|
||||||
"delivery self-check",
|
|
||||||
"queue drained within bound",
|
|
||||||
"forbidden attributes absent"
|
|
||||||
],
|
|
||||||
"negativeFixture": "raw URL and query data must be removed from telemetry"
|
|
||||||
},
|
|
||||||
"FE-RB-005": {
|
|
||||||
"title": "Coherent release rollback",
|
|
||||||
"gateId": "FE-GATE-025",
|
|
||||||
"triggerKinds": ["RELEASE_BLOCKING_DEFECT"],
|
|
||||||
"containment": "select a prior immutable tuple, verify asset/config/API compatibility, atomically switch, and smoke",
|
|
||||||
"window": "provider recovery target TBD",
|
|
||||||
"escalation": ["release-cache owner", "release approver/hosting owner"],
|
|
||||||
"recoveryEvidence": [
|
|
||||||
"compatibility gate",
|
|
||||||
"release coherence gate",
|
|
||||||
"critical smoke",
|
|
||||||
"release ID in incident timeline"
|
|
||||||
],
|
|
||||||
"negativeFixture": "HTML build A with asset manifest B must be rejected"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
@@ -8,6 +8,7 @@
|
|||||||
"window",
|
"window",
|
||||||
"context",
|
"context",
|
||||||
"metrics",
|
"metrics",
|
||||||
|
"thresholds",
|
||||||
"eligibility",
|
"eligibility",
|
||||||
"status",
|
"status",
|
||||||
"passed"
|
"passed"
|
||||||
@@ -18,12 +19,55 @@
|
|||||||
"window": { "type": "object", "required": ["days", "start", "end"] },
|
"window": { "type": "object", "required": ["days", "start", "end"] },
|
||||||
"context": {
|
"context": {
|
||||||
"type": "object",
|
"type": "object",
|
||||||
"required": ["source", "network", "routeAggregation", "releaseId"]
|
"required": [
|
||||||
|
"source",
|
||||||
|
"sourceSystem",
|
||||||
|
"exportId",
|
||||||
|
"network",
|
||||||
|
"routeAggregation",
|
||||||
|
"releaseId",
|
||||||
|
"privacyApprovalRef",
|
||||||
|
"thresholdDecisionRef",
|
||||||
|
"validationFailures"
|
||||||
|
],
|
||||||
|
"properties": {
|
||||||
|
"source": { "type": "string" },
|
||||||
|
"sourceSystem": { "type": ["string", "null"] },
|
||||||
|
"exportId": { "type": ["string", "null"] },
|
||||||
|
"network": { "const": "production-real-user" },
|
||||||
|
"routeAggregation": { "const": "route-id-only" },
|
||||||
|
"releaseId": { "type": ["string", "null"] },
|
||||||
|
"privacyApprovalRef": { "type": ["string", "null"] },
|
||||||
|
"thresholdDecisionRef": { "type": ["string", "null"] },
|
||||||
|
"validationFailures": {
|
||||||
|
"type": "array",
|
||||||
|
"items": { "type": "string" }
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"additionalProperties": false
|
||||||
|
},
|
||||||
|
"thresholds": {
|
||||||
|
"type": "object",
|
||||||
|
"required": [
|
||||||
|
"p75LcpMs",
|
||||||
|
"p75Cls",
|
||||||
|
"p75InpMs",
|
||||||
|
"minimumEligibleSamples"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"metrics": {
|
||||||
|
"type": "object",
|
||||||
|
"required": ["p75LcpMs", "p75Cls", "p75InpMs"]
|
||||||
},
|
},
|
||||||
"metrics": { "type": "object" },
|
|
||||||
"eligibility": {
|
"eligibility": {
|
||||||
"type": "object",
|
"type": "object",
|
||||||
"required": ["consentRequired", "eligibleSamples", "minimumEligibleSamples"]
|
"required": [
|
||||||
|
"consentRequired",
|
||||||
|
"totalSamples",
|
||||||
|
"eligibleSamples",
|
||||||
|
"minimumEligibleSamples",
|
||||||
|
"routeSamples"
|
||||||
|
]
|
||||||
},
|
},
|
||||||
"status": {
|
"status": {
|
||||||
"enum": ["PASS", "FAIL_THRESHOLD", "FAIL_UNVERIFIED"]
|
"enum": ["PASS", "FAIL_THRESHOLD", "FAIL_UNVERIFIED"]
|
||||||
|
|||||||
@@ -1,42 +0,0 @@
|
|||||||
{
|
|
||||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
||||||
"$id": "ART-FE-RUNBOOK-DRILL@1",
|
|
||||||
"type": "object",
|
|
||||||
"required": [
|
|
||||||
"schemaVersion",
|
|
||||||
"runbookId",
|
|
||||||
"releaseId",
|
|
||||||
"drillTimestamp",
|
|
||||||
"triggerInjected",
|
|
||||||
"triggerAsserted",
|
|
||||||
"containmentAsserted",
|
|
||||||
"escalationPathAsserted",
|
|
||||||
"recoveryAssertions",
|
|
||||||
"negativeFixtureFailedAsExpected",
|
|
||||||
"windowObservedBucket",
|
|
||||||
"passed"
|
|
||||||
],
|
|
||||||
"properties": {
|
|
||||||
"schemaVersion": { "const": 1 },
|
|
||||||
"runbookId": { "pattern": "^FE-RB-00[1-5]$" },
|
|
||||||
"releaseId": { "type": "string", "minLength": 1 },
|
|
||||||
"drillTimestamp": { "type": "string", "format": "date-time" },
|
|
||||||
"triggerInjected": { "type": "string" },
|
|
||||||
"triggerAsserted": { "type": "boolean" },
|
|
||||||
"containmentAsserted": { "type": "boolean" },
|
|
||||||
"escalationPathAsserted": { "type": "boolean" },
|
|
||||||
"recoveryAssertions": {
|
|
||||||
"type": "array",
|
|
||||||
"minItems": 4,
|
|
||||||
"items": {
|
|
||||||
"type": "object",
|
|
||||||
"required": ["assertion", "evidence", "passed"]
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"negativeFixtureFailedAsExpected": { "type": "boolean" },
|
|
||||||
"windowObservedBucket": { "type": "string" },
|
|
||||||
"providerVerificationRequired": { "type": "boolean" },
|
|
||||||
"passed": { "type": "boolean" }
|
|
||||||
},
|
|
||||||
"additionalProperties": false
|
|
||||||
}
|
|
||||||
@@ -1,23 +0,0 @@
|
|||||||
# Architecture overview
|
|
||||||
|
|
||||||
This Mermaid view is a repository-local implementation projection. The
|
|
||||||
`PASS_SCOPED` reviewer evidence applies to the canonical draw.io diagram named
|
|
||||||
in `review-ledger.json`, not automatically to edits in this file.
|
|
||||||
|
|
||||||
```mermaid
|
|
||||||
flowchart LR
|
|
||||||
Bootstrap[bootstrap / composition root] --> Presentation[presentation]
|
|
||||||
Bootstrap --> Adapters[adapters]
|
|
||||||
Presentation --> Application[application]
|
|
||||||
Adapters --> Application
|
|
||||||
Application --> Domain[domain]
|
|
||||||
Contracts[contract registries] --> Bootstrap
|
|
||||||
Contracts --> Adapters
|
|
||||||
Contracts --> Presentation
|
|
||||||
```
|
|
||||||
|
|
||||||
Dependencies point inward. Presentation calls application use cases, adapters
|
|
||||||
implement application ports, and only the composition root selects concrete
|
|
||||||
adapters. Contract registries are the single named source for routes, API
|
|
||||||
operations, environment values, storage keys, errors, queries, telemetry, and
|
|
||||||
release tokens.
|
|
||||||
@@ -1,22 +0,0 @@
|
|||||||
# Imported scoped diagram review evidence
|
|
||||||
|
|
||||||
This ledger entry consumes the canonical evidence already recorded by the
|
|
||||||
`ca-skeleton-frontend-operational-contract` project note. It does not claim
|
|
||||||
review of the repository-local Mermaid projections or of the complete
|
|
||||||
production deployment topology.
|
|
||||||
|
|
||||||
- Reviewer: `wiki-diagram-reviewer`
|
|
||||||
- Standard: `rules/diagram-standards.md` v2
|
|
||||||
- Canonical report:
|
|
||||||
`docs/superpowers/specs/2026-07-18-ca-skeleton-frontend-operational-contract-review/diagram-review.md`
|
|
||||||
- Canonical report SHA-256:
|
|
||||||
`b4d2a35e4f07e176717786408f98dab5cee1047f77f6ff61f5faeddfccd78a29`
|
|
||||||
|
|
||||||
| Canonical diagram | SHA-256 | Score | Verdict | Reviewed scope |
|
|
||||||
| --- | --- | ---: | --- | --- |
|
|
||||||
| `raw/diagrams/ca-skeleton-frontend/architecture-overview-2026-07-18.drawio` | `c0ae56c9c964c5c6e698ab7dcc91736b9b811b2b834381817905db81c4230ba0` | 100 | PASS | Clean Architecture compile-time dependency ownership |
|
|
||||||
| `raw/diagrams/ca-skeleton-frontend/architecture-deployment-2026-07-18.drawio` | `9a654326fb840ddf24b832221ff7eec4b8fadd9f87ad84174fccfa3bfcd1a25b` | 100 | PASS | immutable static assets and mutable `/config.json` delivery |
|
|
||||||
|
|
||||||
The canonical report explicitly limits this `PASS_SCOPED`: it does not verify
|
|
||||||
the complete release/rollback topology, the implementation topology, or live
|
|
||||||
hosting state.
|
|
||||||
@@ -1,29 +0,0 @@
|
|||||||
{
|
|
||||||
"schemaVersion": 1,
|
|
||||||
"status": "PASS_SCOPED",
|
|
||||||
"reviewer": "wiki-diagram-reviewer",
|
|
||||||
"standard": "rules/diagram-standards.md v2",
|
|
||||||
"evidenceReport": {
|
|
||||||
"repoPath": "docs/architecture/review-evidence.md",
|
|
||||||
"canonicalPath": "docs/superpowers/specs/2026-07-18-ca-skeleton-frontend-operational-contract-review/diagram-review.md",
|
|
||||||
"canonicalSha256": "b4d2a35e4f07e176717786408f98dab5cee1047f77f6ff61f5faeddfccd78a29"
|
|
||||||
},
|
|
||||||
"reviews": {
|
|
||||||
"overview": {
|
|
||||||
"sourcePath": "raw/diagrams/ca-skeleton-frontend/architecture-overview-2026-07-18.drawio",
|
|
||||||
"sha256": "c0ae56c9c964c5c6e698ab7dcc91736b9b811b2b834381817905db81c4230ba0",
|
|
||||||
"score": 100,
|
|
||||||
"verdict": "PASS",
|
|
||||||
"thresholdSatisfied": true,
|
|
||||||
"scope": "Clean Architecture compile-time dependency ownership"
|
|
||||||
},
|
|
||||||
"staticDelivery": {
|
|
||||||
"sourcePath": "raw/diagrams/ca-skeleton-frontend/architecture-deployment-2026-07-18.drawio",
|
|
||||||
"sha256": "9a654326fb840ddf24b832221ff7eec4b8fadd9f87ad84174fccfa3bfcd1a25b",
|
|
||||||
"score": 100,
|
|
||||||
"verdict": "PASS",
|
|
||||||
"thresholdSatisfied": true,
|
|
||||||
"scope": "immutable static assets and mutable /config.json delivery"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
@@ -1,25 +0,0 @@
|
|||||||
# Static asset and runtime-config delivery
|
|
||||||
|
|
||||||
This Mermaid view is a repository-local implementation projection. The
|
|
||||||
`PASS_SCOPED` reviewer evidence applies only to the canonical static-delivery
|
|
||||||
draw.io scope recorded in `review-ledger.json`.
|
|
||||||
|
|
||||||
```mermaid
|
|
||||||
sequenceDiagram
|
|
||||||
participant CI
|
|
||||||
participant ImmutableRelease
|
|
||||||
participant ActivePointer
|
|
||||||
participant Browser
|
|
||||||
CI->>ImmutableRelease: upload hashed assets
|
|
||||||
CI->>ImmutableRelease: upload release manifest
|
|
||||||
CI->>ImmutableRelease: upload runtime config
|
|
||||||
CI->>ImmutableRelease: probe asset reachability
|
|
||||||
CI->>ActivePointer: atomically switch HTML
|
|
||||||
Browser->>ActivePointer: fetch revalidated HTML
|
|
||||||
Browser->>ImmutableRelease: fetch no-store config and manifest
|
|
||||||
Browser->>ImmutableRelease: fetch immutable hashed assets
|
|
||||||
CI->>Browser: boot, route, API, and reload-loop smoke
|
|
||||||
```
|
|
||||||
|
|
||||||
Rollback changes the active pointer only after confirming that the prior
|
|
||||||
immutable release has a coherent HTML/assets/config/API/manifest tuple.
|
|
||||||
@@ -1,41 +0,0 @@
|
|||||||
# CI quality-gate orchestration
|
|
||||||
|
|
||||||
`config/ci/gates.json` is the executable registry for all 26 gates. The Gitea
|
|
||||||
adapter runs each gate as an independent matrix check with full fan-out and no
|
|
||||||
soft-fail wiring.
|
|
||||||
|
|
||||||
The dependency graph is:
|
|
||||||
|
|
||||||
```text
|
|
||||||
MERGE_READY
|
|
||||||
-> RELEASE_READY
|
|
||||||
-> PROD_PROMOTION_READY
|
|
||||||
-> FIELD_SLO_READY
|
|
||||||
|
|
||||||
DOCUMENTATION_READY (off-chain)
|
|
||||||
```
|
|
||||||
|
|
||||||
Pull requests and `develop` pushes evaluate merge readiness. Version tags
|
|
||||||
evaluate merge then release readiness. Production and field evaluation require
|
|
||||||
an explicit workflow dispatch. The field tier cannot pass until the 28-day
|
|
||||||
sample threshold decision is recorded. Documentation readiness consumes the
|
|
||||||
canonical project-note evidence in which both scoped diagrams already received
|
|
||||||
100/100 `PASS_SCOPED`; the repo ledger preserves the evidence scope and
|
|
||||||
canonical digests.
|
|
||||||
|
|
||||||
All jobs upload the shared `artifacts/` tree even after failure. Numeric
|
|
||||||
retention remains an organization/provider decision; the workflow intentionally
|
|
||||||
does not invent `retention-days`. The relative minimums are recorded in the
|
|
||||||
registry: merge evidence through the PR decision, coherent release evidence
|
|
||||||
through the next release promotion, drill evidence through the next production
|
|
||||||
promotion, and field evidence through aggregation.
|
|
||||||
|
|
||||||
Repository variables required by higher tiers:
|
|
||||||
|
|
||||||
- `HOSTING_BASE_URL` for live header verification
|
|
||||||
- `FIELD_WEB_VITALS_INPUT` for the privacy-approved field sample document
|
|
||||||
- `MIN_ELIGIBLE_SAMPLES` after the baseline decision
|
|
||||||
|
|
||||||
Branch protection must mark each `FE-GATE-* / <name>` check required for its
|
|
||||||
declared tier. This repository cannot configure server-side protection by
|
|
||||||
committing a file.
|
|
||||||
@@ -13,5 +13,10 @@ Performance evidence is deliberately split by measurement context:
|
|||||||
The field minimum eligible-sample threshold is intentionally unresolved until
|
The field minimum eligible-sample threshold is intentionally unresolved until
|
||||||
a privacy-approved telemetry baseline exists. Therefore the field command
|
a privacy-approved telemetry baseline exists. Therefore the field command
|
||||||
fails closed with `FAIL_UNVERIFIED` when run against the example input. Provide
|
fails closed with `FAIL_UNVERIFIED` when run against the example input. Provide
|
||||||
`FIELD_WEB_VITALS_INPUT` and a reviewed `MIN_ELIGIBLE_SAMPLES` only after that
|
`FIELD_WEB_VITALS_INPUT` and `MIN_ELIGIBLE_SAMPLES` only after that decision is
|
||||||
decision is recorded.
|
recorded. The external input must identify a production release and an exact
|
||||||
|
28-day export window, name the source/export, carry privacy-approval and
|
||||||
|
threshold-decision references, and contain only non-negative route-ID samples.
|
||||||
|
The environment threshold must be a positive integer equal to the approved
|
||||||
|
decision embedded in the input. Invalid metadata fails as `FAIL_UNVERIFIED`;
|
||||||
|
the example can never serve as production evidence.
|
||||||
|
|||||||
@@ -1,9 +0,0 @@
|
|||||||
# FE-RB-001 — Boot configuration failure
|
|
||||||
|
|
||||||
Trigger on `BOOT_CONFIG_FAILURE` after the single bounded refetch fails. Stop
|
|
||||||
product route mounting and show the safe support shell; the planned owner
|
|
||||||
triage target is five minutes. Escalate from the environment/config owner to
|
|
||||||
the release owner.
|
|
||||||
|
|
||||||
Close only after a clean-session boot mounts the product root, config
|
|
||||||
validation evidence passes, and repeated boot-error telemetry is absent.
|
|
||||||
@@ -1,11 +0,0 @@
|
|||||||
# FE-RB-002 — Chunk or deployment mismatch
|
|
||||||
|
|
||||||
Trigger on `CHUNK_LOAD_FAILURE`, `RELEASE_MANIFEST_FAILURE`, or
|
|
||||||
`DEPLOY_MISMATCH`. Warn when dirty state may be lost, fetch the manifest
|
|
||||||
`no-store` once, record the release pair, and allow only one reload. The
|
|
||||||
planned release-owner triage target is five minutes. Escalate to the hosting/CDN
|
|
||||||
owner.
|
|
||||||
|
|
||||||
Close only after entry/lazy assets are reachable, the manifest parses into a
|
|
||||||
coherent tuple, a second automatic reload is blocked, and the critical route
|
|
||||||
smoke passes.
|
|
||||||
@@ -1,10 +0,0 @@
|
|||||||
# FE-RB-003 — Backend API degradation
|
|
||||||
|
|
||||||
Trigger when terminal network/timeout/5xx failures exceed the rolling
|
|
||||||
five-minute threshold or on one `SCHEMA_MISMATCH`. Do not expand client retry
|
|
||||||
caps, do not retry schema mismatches, and never retry an unkeyed mutation.
|
|
||||||
Escalate from the API client owner to backend operations and then release
|
|
||||||
compatibility; the planned first-classification target is ten minutes.
|
|
||||||
|
|
||||||
Close only after the failure rate returns to baseline, retry amplification is
|
|
||||||
absent, critical read/write smoke passes, and schema fixtures pass.
|
|
||||||
@@ -1,9 +0,0 @@
|
|||||||
# FE-RB-004 — Telemetry sink failure
|
|
||||||
|
|
||||||
Trigger on sink network/non-2xx errors, queue overflow, or adapter
|
|
||||||
initialization failure. Keep product flows available, bound the queue, and do
|
|
||||||
not recursively report to the failed sink. Escalate from observability to the
|
|
||||||
telemetry platform owner; the planned triage target is fifteen minutes.
|
|
||||||
|
|
||||||
Close only after product e2e remains unaffected, delivery self-check succeeds,
|
|
||||||
the queue drains within its bound, and the forbidden-attribute scan passes.
|
|
||||||
@@ -1,13 +0,0 @@
|
|||||||
# FE-RB-005 — Coherent release rollback
|
|
||||||
|
|
||||||
Trigger on a release-blocking boot, chunk, render, API, or security defect when
|
|
||||||
a safe forward fix is not demonstrated inside the incident window. Select a
|
|
||||||
prior immutable release, verify its asset/config/API tuple, atomically switch
|
|
||||||
the complete set, perform the provider cache action, and run smoke checks.
|
|
||||||
Escalate from the release-cache owner to the release approver/hosting owner.
|
|
||||||
The provider recovery target remains TBD until hosting is selected.
|
|
||||||
|
|
||||||
Close only when compatibility and release-coherence gates pass, critical smoke
|
|
||||||
passes, repeated `DEPLOY_MISMATCH` is absent, and the incident timeline records
|
|
||||||
the restored release ID. Pointer-switch or cache-purge completion alone is not
|
|
||||||
recovery evidence.
|
|
||||||
+1
-6
@@ -36,12 +36,7 @@
|
|||||||
"verify:hosting-headers": "node scripts/verify-hosting-headers.mjs",
|
"verify:hosting-headers": "node scripts/verify-hosting-headers.mjs",
|
||||||
"check:bundle": "node scripts/generate-supply-chain.mjs && node scripts/check-bundle.mjs",
|
"check:bundle": "node scripts/generate-supply-chain.mjs && node scripts/check-bundle.mjs",
|
||||||
"test:performance": "node scripts/test-performance.mjs",
|
"test:performance": "node scripts/test-performance.mjs",
|
||||||
"collect:web-vitals-evidence": "node scripts/collect-web-vitals-evidence.mjs",
|
"collect:web-vitals-evidence": "node scripts/collect-web-vitals-evidence.mjs"
|
||||||
"drill:runbook": "node scripts/drill-runbook.mjs",
|
|
||||||
"drill:runbooks": "corepack pnpm drill:runbook -- FE-RB-001 && corepack pnpm drill:runbook -- FE-RB-002 && corepack pnpm drill:runbook -- FE-RB-003 && corepack pnpm drill:runbook -- FE-RB-004 && corepack pnpm drill:runbook -- FE-RB-005",
|
|
||||||
"ci:gate": "node scripts/run-ci-gate.mjs",
|
|
||||||
"check:ci": "node scripts/check-ci-contract.mjs",
|
|
||||||
"verify:documentation": "node scripts/verify-documentation-readiness.mjs"
|
|
||||||
},
|
},
|
||||||
"dependencies": {
|
"dependencies": {
|
||||||
"@tanstack/react-query": "5.101.4",
|
"@tanstack/react-query": "5.101.4",
|
||||||
|
|||||||
+22
-15
@@ -1,6 +1,7 @@
|
|||||||
import { readFile, writeFile } from "node:fs/promises";
|
import { readFile, writeFile } from "node:fs/promises";
|
||||||
|
|
||||||
import { evaluateBundleBudget } from "../src/application/policies/performance-budgets.js";
|
import { evaluateBundleBudget } from "../src/application/policies/performance-budgets.js";
|
||||||
|
import { classifyViteJavascript } from "./lib/classify-vite-bundle.mjs";
|
||||||
|
|
||||||
const report =
|
const report =
|
||||||
/** @type {{
|
/** @type {{
|
||||||
@@ -10,7 +11,7 @@ const report =
|
|||||||
JSON.parse(await readFile("artifacts/performance/bundle.json", "utf8"))
|
JSON.parse(await readFile("artifacts/performance/bundle.json", "utf8"))
|
||||||
);
|
);
|
||||||
const viteManifest =
|
const viteManifest =
|
||||||
/** @type {Record<string, { file: string, isEntry?: boolean }>} */ (
|
/** @type {Record<string, { file: string, isEntry?: boolean, imports?: string[] }>} */ (
|
||||||
JSON.parse(await readFile("dist/.vite/manifest.json", "utf8"))
|
JSON.parse(await readFile("dist/.vite/manifest.json", "utf8"))
|
||||||
);
|
);
|
||||||
const budgets =
|
const budgets =
|
||||||
@@ -21,24 +22,19 @@ const budgets =
|
|||||||
const outputByPath = new Map(
|
const outputByPath = new Map(
|
||||||
report.outputs.map((output) => [output.path.replace(/^dist\//, ""), output]),
|
report.outputs.map((output) => [output.path.replace(/^dist\//, ""), output]),
|
||||||
);
|
);
|
||||||
const initialFiles = new Set(
|
const classification = classifyViteJavascript(viteManifest);
|
||||||
Object.values(viteManifest)
|
const initialJsGzipBytes = classification.initialFiles.reduce(
|
||||||
.filter((entry) => entry.isEntry)
|
|
||||||
.map((entry) => entry.file),
|
|
||||||
);
|
|
||||||
const lazyFiles = new Set(
|
|
||||||
Object.values(viteManifest)
|
|
||||||
.filter((entry) => !entry.isEntry && entry.file.endsWith(".js"))
|
|
||||||
.map((entry) => entry.file),
|
|
||||||
);
|
|
||||||
const initialJsGzipBytes = [...initialFiles].reduce(
|
|
||||||
(total, file) => total + (outputByPath.get(file)?.gzipBytes ?? 0),
|
(total, file) => total + (outputByPath.get(file)?.gzipBytes ?? 0),
|
||||||
0,
|
0,
|
||||||
);
|
);
|
||||||
const lazyChunks = [...lazyFiles].map((file) => ({
|
const lazyChunks = classification.lazyFiles.map((file) => ({
|
||||||
path: file,
|
path: file,
|
||||||
gzipBytes: outputByPath.get(file)?.gzipBytes ?? 0,
|
gzipBytes: outputByPath.get(file)?.gzipBytes ?? 0,
|
||||||
}));
|
}));
|
||||||
|
const missingOutputs = [
|
||||||
|
...classification.initialFiles,
|
||||||
|
...classification.lazyFiles,
|
||||||
|
].filter((file) => !outputByPath.has(file));
|
||||||
const measurements = { initialJsGzipBytes, lazyChunks };
|
const measurements = { initialJsGzipBytes, lazyChunks };
|
||||||
const result = evaluateBundleBudget(measurements, budgets);
|
const result = evaluateBundleBudget(measurements, budgets);
|
||||||
const fixtures = [
|
const fixtures = [
|
||||||
@@ -70,10 +66,16 @@ const fixtures = [
|
|||||||
).passed,
|
).passed,
|
||||||
},
|
},
|
||||||
];
|
];
|
||||||
const passed = result.passed && fixtures.every((fixture) => fixture.passed);
|
const passed =
|
||||||
|
result.passed &&
|
||||||
|
fixtures.every((fixture) => fixture.passed) &&
|
||||||
|
classification.missingImports.length === 0 &&
|
||||||
|
missingOutputs.length === 0;
|
||||||
const completedReport = {
|
const completedReport = {
|
||||||
...report,
|
...report,
|
||||||
measurements,
|
measurements,
|
||||||
|
classification,
|
||||||
|
missingOutputs,
|
||||||
thresholds: budgets,
|
thresholds: budgets,
|
||||||
results: result,
|
results: result,
|
||||||
fixtures,
|
fixtures,
|
||||||
@@ -85,7 +87,12 @@ await writeFile(
|
|||||||
`${JSON.stringify(completedReport, null, 2)}\n`,
|
`${JSON.stringify(completedReport, null, 2)}\n`,
|
||||||
);
|
);
|
||||||
if (!passed) {
|
if (!passed) {
|
||||||
process.stderr.write("Bundle budget exceeded.\n");
|
process.stderr.write(
|
||||||
|
`Bundle budget or manifest integrity failed: ${[
|
||||||
|
...classification.missingImports,
|
||||||
|
...missingOutputs,
|
||||||
|
].join(", ")}\n`,
|
||||||
|
);
|
||||||
process.exit(1);
|
process.exit(1);
|
||||||
}
|
}
|
||||||
process.stdout.write(
|
process.stdout.write(
|
||||||
|
|||||||
@@ -1,111 +0,0 @@
|
|||||||
import { mkdir, readFile, writeFile } from "node:fs/promises";
|
|
||||||
|
|
||||||
import {
|
|
||||||
evaluatePromotionReadiness,
|
|
||||||
PROMOTION_FORMULA,
|
|
||||||
} from "../src/application/policies/promotion-readiness.js";
|
|
||||||
|
|
||||||
const document = JSON.parse(await readFile("config/ci/gates.json", "utf8"));
|
|
||||||
const workflow = await readFile(document.providerAdapter, "utf8");
|
|
||||||
const failures = [];
|
|
||||||
const stageFormula = {
|
|
||||||
merge: PROMOTION_FORMULA.MERGE_READY,
|
|
||||||
release: PROMOTION_FORMULA.RELEASE_READY,
|
|
||||||
production: PROMOTION_FORMULA.PROD_PROMOTION_READY,
|
|
||||||
field: PROMOTION_FORMULA.FIELD_SLO_READY,
|
|
||||||
documentation: PROMOTION_FORMULA.DOCUMENTATION_READY,
|
|
||||||
};
|
|
||||||
|
|
||||||
for (const [stage, expectedGates] of Object.entries(stageFormula)) {
|
|
||||||
const actual = document.stages[stage]?.gates;
|
|
||||||
if (JSON.stringify(actual) !== JSON.stringify(expectedGates)) {
|
|
||||||
failures.push(`${stage} gate formula drift`);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
const configuredGateIds = Object.keys(document.gates).sort();
|
|
||||||
const expectedGateIds = Array.from(
|
|
||||||
{ length: 26 },
|
|
||||||
(_, index) => `FE-GATE-${String(index + 1).padStart(3, "0")}`,
|
|
||||||
);
|
|
||||||
if (JSON.stringify(configuredGateIds) !== JSON.stringify(expectedGateIds)) {
|
|
||||||
failures.push("gate registry must contain FE-GATE-001..026 exactly once");
|
|
||||||
}
|
|
||||||
|
|
||||||
for (const [gateId, gate] of Object.entries(document.gates)) {
|
|
||||||
if (!gate.steps?.length || !gate.evidence?.length || !gate.retentionClass) {
|
|
||||||
failures.push(`${gateId} lacks command, evidence, or retention wiring`);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
const forbiddenWorkflowPatterns = [
|
|
||||||
/continue-on-error\s*:/,
|
|
||||||
/retention-days\s*:/,
|
|
||||||
/allow_failure\s*:/,
|
|
||||||
];
|
|
||||||
for (const pattern of forbiddenWorkflowPatterns) {
|
|
||||||
if (pattern.test(workflow)) {
|
|
||||||
failures.push(`workflow contains forbidden downgrade/unsupported setting ${pattern}`);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
for (const requiredToken of [
|
|
||||||
"merge_gate:",
|
|
||||||
"release_gate:",
|
|
||||||
"production_gate:",
|
|
||||||
"field_gate:",
|
|
||||||
"documentation_gate:",
|
|
||||||
"needs: merge_gate",
|
|
||||||
"needs: release_gate",
|
|
||||||
"needs: production_gate",
|
|
||||||
"actions/upload-artifact@v4",
|
|
||||||
"if: always()",
|
|
||||||
]) {
|
|
||||||
if (!workflow.includes(requiredToken)) {
|
|
||||||
failures.push(`workflow missing ${requiredToken}`);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
const passingResults = Object.fromEntries(
|
|
||||||
expectedGateIds.map((gateId) => [gateId, /** @type {const} */ ("PASS")]),
|
|
||||||
);
|
|
||||||
const allPass = evaluatePromotionReadiness(passingResults);
|
|
||||||
const negativeFixtures = [];
|
|
||||||
for (const [readiness, gateIds] of Object.entries(PROMOTION_FORMULA)) {
|
|
||||||
const failedGate = gateIds[0];
|
|
||||||
const result = evaluatePromotionReadiness({
|
|
||||||
...passingResults,
|
|
||||||
[failedGate]: "FAIL",
|
|
||||||
});
|
|
||||||
const passed =
|
|
||||||
/** @type {Readonly<Record<string, boolean>>} */ (result)[readiness] ===
|
|
||||||
false;
|
|
||||||
negativeFixtures.push({ readiness, failedGate, passed });
|
|
||||||
if (!passed) failures.push(`${readiness} did not fail closed`);
|
|
||||||
}
|
|
||||||
if (!Object.values(allPass).every(Boolean)) {
|
|
||||||
failures.push("all-PASS formula did not produce every readiness state");
|
|
||||||
}
|
|
||||||
|
|
||||||
const report = {
|
|
||||||
schemaVersion: 1,
|
|
||||||
generatedAt: new Date().toISOString(),
|
|
||||||
providerAdapter: document.providerAdapter,
|
|
||||||
gateCount: configuredGateIds.length,
|
|
||||||
noDowngrade: failures.every(
|
|
||||||
(failure) => !failure.includes("downgrade"),
|
|
||||||
),
|
|
||||||
durationStatus: document.retention.durationStatus,
|
|
||||||
negativeFixtures,
|
|
||||||
failures,
|
|
||||||
passed: failures.length === 0,
|
|
||||||
};
|
|
||||||
await mkdir("artifacts/quality", { recursive: true });
|
|
||||||
await writeFile(
|
|
||||||
"artifacts/quality/ci-contract.json",
|
|
||||||
`${JSON.stringify(report, null, 2)}\n`,
|
|
||||||
);
|
|
||||||
if (failures.length > 0) {
|
|
||||||
process.stderr.write(`CI contract failed:\n${failures.join("\n")}\n`);
|
|
||||||
process.exit(1);
|
|
||||||
}
|
|
||||||
process.stdout.write("CI contract: 26 blocking gates and 4-tier graph PASS\n");
|
|
||||||
@@ -4,23 +4,19 @@ import {
|
|||||||
evaluateFieldBudget,
|
evaluateFieldBudget,
|
||||||
percentile75,
|
percentile75,
|
||||||
} from "../src/application/policies/performance-budgets.js";
|
} from "../src/application/policies/performance-budgets.js";
|
||||||
|
import { validateFieldEvidenceInput } from "./lib/field-vitals-evidence.mjs";
|
||||||
|
|
||||||
const inputPath =
|
const inputPath =
|
||||||
process.env.FIELD_WEB_VITALS_INPUT ||
|
process.env.FIELD_WEB_VITALS_INPUT ??
|
||||||
"config/performance/field-input.example.json";
|
"config/performance/field-input.example.json";
|
||||||
const input =
|
const rawInput = JSON.parse(await readFile(inputPath, "utf8"));
|
||||||
/** @type {{
|
const now = new Date();
|
||||||
* releaseId: string,
|
const validation = validateFieldEvidenceInput(
|
||||||
* samples: Array<{
|
rawInput,
|
||||||
* timestamp: string,
|
process.env.MIN_ELIGIBLE_SAMPLES,
|
||||||
* consent: boolean,
|
now,
|
||||||
* releaseId: string,
|
);
|
||||||
* routeId: string,
|
const input = validation.data;
|
||||||
* lcpMs: number,
|
|
||||||
* cls: number,
|
|
||||||
* inpMs: number
|
|
||||||
* }>
|
|
||||||
* }} */ (JSON.parse(await readFile(inputPath, "utf8")));
|
|
||||||
const configured =
|
const configured =
|
||||||
/** @type {{
|
/** @type {{
|
||||||
* p75LcpMs: number,
|
* p75LcpMs: number,
|
||||||
@@ -30,17 +26,17 @@ const configured =
|
|||||||
* }} */ (
|
* }} */ (
|
||||||
JSON.parse(await readFile("config/performance/budgets.json", "utf8")).field
|
JSON.parse(await readFile("config/performance/budgets.json", "utf8")).field
|
||||||
);
|
);
|
||||||
const minimumEligibleSamples = process.env.MIN_ELIGIBLE_SAMPLES
|
const minimumEligibleSamples = validation.minimumEligibleSamples;
|
||||||
? Number(process.env.MIN_ELIGIBLE_SAMPLES)
|
const fallbackEnd = now;
|
||||||
: configured.minimumEligibleSamples;
|
const fallbackStart = new Date(fallbackEnd);
|
||||||
const end = new Date();
|
fallbackStart.setUTCDate(fallbackStart.getUTCDate() - 28);
|
||||||
const start = new Date(end);
|
const start = input ? new Date(input.window.start) : fallbackStart;
|
||||||
start.setUTCDate(start.getUTCDate() - 28);
|
const end = input ? new Date(input.window.end) : fallbackEnd;
|
||||||
const eligible = input.samples.filter((sample) => {
|
const eligible = (input?.samples ?? []).filter((sample) => {
|
||||||
const timestamp = new Date(sample.timestamp);
|
const timestamp = new Date(sample.timestamp);
|
||||||
return (
|
return (
|
||||||
sample.consent === true &&
|
sample.consent === true &&
|
||||||
sample.releaseId === input.releaseId &&
|
sample.releaseId === input?.releaseId &&
|
||||||
timestamp >= start &&
|
timestamp >= start &&
|
||||||
timestamp <= end
|
timestamp <= end
|
||||||
);
|
);
|
||||||
@@ -55,6 +51,8 @@ const result = evaluateFieldBudget(
|
|||||||
{ metrics, eligibleSamples: eligible.length },
|
{ metrics, eligibleSamples: eligible.length },
|
||||||
thresholds,
|
thresholds,
|
||||||
);
|
);
|
||||||
|
const passed = validation.passed && result.passed;
|
||||||
|
const status = validation.passed ? result.status : "FAIL_UNVERIFIED";
|
||||||
const routeSamples = Object.fromEntries(
|
const routeSamples = Object.fromEntries(
|
||||||
Object.entries(
|
Object.entries(
|
||||||
eligible.reduce(
|
eligible.reduce(
|
||||||
@@ -68,24 +66,30 @@ const routeSamples = Object.fromEntries(
|
|||||||
);
|
);
|
||||||
const report = {
|
const report = {
|
||||||
schemaVersion: 1,
|
schemaVersion: 1,
|
||||||
generatedAt: end.toISOString(),
|
generatedAt: now.toISOString(),
|
||||||
window: { days: 28, start: start.toISOString(), end: end.toISOString() },
|
window: { days: 28, start: start.toISOString(), end: end.toISOString() },
|
||||||
context: {
|
context: {
|
||||||
source: inputPath,
|
source: inputPath,
|
||||||
|
sourceSystem: input?.source.system ?? null,
|
||||||
|
exportId: input?.source.exportId ?? null,
|
||||||
network: "production-real-user",
|
network: "production-real-user",
|
||||||
routeAggregation: "route-id-only",
|
routeAggregation: "route-id-only",
|
||||||
releaseId: input.releaseId,
|
releaseId: input?.releaseId ?? null,
|
||||||
|
privacyApprovalRef: input?.privacy.approvalRef ?? null,
|
||||||
|
thresholdDecisionRef: input?.thresholdDecision.evidenceRef ?? null,
|
||||||
|
validationFailures: validation.failures,
|
||||||
},
|
},
|
||||||
metrics,
|
metrics,
|
||||||
thresholds,
|
thresholds,
|
||||||
eligibility: {
|
eligibility: {
|
||||||
consentRequired: true,
|
consentRequired: true,
|
||||||
|
totalSamples: input?.samples.length ?? 0,
|
||||||
eligibleSamples: eligible.length,
|
eligibleSamples: eligible.length,
|
||||||
minimumEligibleSamples,
|
minimumEligibleSamples,
|
||||||
routeSamples,
|
routeSamples,
|
||||||
},
|
},
|
||||||
status: result.status,
|
status,
|
||||||
passed: result.passed,
|
passed,
|
||||||
};
|
};
|
||||||
|
|
||||||
await mkdir("artifacts/performance", { recursive: true });
|
await mkdir("artifacts/performance", { recursive: true });
|
||||||
@@ -93,9 +97,9 @@ await writeFile(
|
|||||||
"artifacts/performance/field-web-vitals.json",
|
"artifacts/performance/field-web-vitals.json",
|
||||||
`${JSON.stringify(report, null, 2)}\n`,
|
`${JSON.stringify(report, null, 2)}\n`,
|
||||||
);
|
);
|
||||||
if (!result.passed) {
|
if (!passed) {
|
||||||
process.stderr.write(
|
process.stderr.write(
|
||||||
`Field Web Vitals: ${result.status} (minimum eligible sample threshold and 28-day production data are required)\n`,
|
`Field Web Vitals: ${status} (approved threshold decision and valid 28-day production evidence are required)\n`,
|
||||||
);
|
);
|
||||||
process.exit(1);
|
process.exit(1);
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -1,309 +0,0 @@
|
|||||||
import { access, mkdir, readFile, writeFile } from "node:fs/promises";
|
|
||||||
|
|
||||||
import { shouldRetry } from "../src/adapters/http/retry-policy.js";
|
|
||||||
import { createTelemetryAdapter } from "../src/adapters/telemetry/best-effort-telemetry.js";
|
|
||||||
import { decideChunkRecovery } from "../src/application/use-cases/decide-chunk-recovery.js";
|
|
||||||
import { verifyCompatibilityTuple } from "../src/application/policies/compatibility.js";
|
|
||||||
import { validateRuntimeConfig } from "../src/bootstrap/runtime-config-schema.js";
|
|
||||||
import { projectTelemetryEvent } from "../src/contracts/telemetry.js";
|
|
||||||
import { compareReleaseToRuntime } from "../src/contracts/release-tokens.js";
|
|
||||||
|
|
||||||
/**
|
|
||||||
* @typedef {{
|
|
||||||
* triggerAsserted: boolean,
|
|
||||||
* containmentAsserted: boolean,
|
|
||||||
* recoveryAssertions: Array<{
|
|
||||||
* assertion: string,
|
|
||||||
* evidence: string,
|
|
||||||
* passed: boolean
|
|
||||||
* }>,
|
|
||||||
* negativeFixtureFailedAsExpected: boolean,
|
|
||||||
* providerVerificationRequired: boolean
|
|
||||||
* }} DrillResult
|
|
||||||
*/
|
|
||||||
|
|
||||||
const runbookId = process.argv
|
|
||||||
.slice(2)
|
|
||||||
.find((argument) => /^FE-RB-00[1-5]$/.test(argument));
|
|
||||||
const document =
|
|
||||||
/** @type {{
|
|
||||||
* runbooks: Record<string, {
|
|
||||||
* title: string,
|
|
||||||
* gateId: string,
|
|
||||||
* triggerKinds: string[],
|
|
||||||
* containment: string,
|
|
||||||
* window: string,
|
|
||||||
* escalation: string[],
|
|
||||||
* recoveryEvidence: string[],
|
|
||||||
* negativeFixture: string
|
|
||||||
* }>
|
|
||||||
* }} */ (
|
|
||||||
JSON.parse(await readFile("config/runbooks/runbooks.json", "utf8"))
|
|
||||||
);
|
|
||||||
const specification = runbookId ? document.runbooks[runbookId] : undefined;
|
|
||||||
if (!runbookId || !specification) {
|
|
||||||
process.stderr.write("Usage: drill:runbook -- FE-RB-001..FE-RB-005\n");
|
|
||||||
process.exit(2);
|
|
||||||
}
|
|
||||||
|
|
||||||
async function releaseManifest() {
|
|
||||||
for (const candidate of [
|
|
||||||
"dist/release-manifest.json",
|
|
||||||
"public/release-manifest.json",
|
|
||||||
]) {
|
|
||||||
try {
|
|
||||||
return JSON.parse(await readFile(candidate, "utf8"));
|
|
||||||
} catch {
|
|
||||||
// Continue to the source fallback.
|
|
||||||
}
|
|
||||||
}
|
|
||||||
throw new Error("Release manifest is unavailable.");
|
|
||||||
}
|
|
||||||
|
|
||||||
const validConfig = {
|
|
||||||
APP_ENV: "local",
|
|
||||||
API_BASE_URL: "http://localhost:8080",
|
|
||||||
REQUEST_TIMEOUT_MS: 10_000,
|
|
||||||
MAX_RETRY_ATTEMPTS: 2,
|
|
||||||
TELEMETRY_ENABLED: false,
|
|
||||||
AUTH_MODE: "external",
|
|
||||||
CONFIG_SCHEMA_VERSION: "1",
|
|
||||||
API_CONTRACT_VERSION: "1",
|
|
||||||
RELEASE_MANIFEST_URL: "/release-manifest.json",
|
|
||||||
BUILD_ID: "local-build",
|
|
||||||
RELEASE_ID: "local-release",
|
|
||||||
};
|
|
||||||
|
|
||||||
/** @param {string} assertion @param {string} evidence @param {boolean} passed */
|
|
||||||
function assertion(assertion, evidence, passed) {
|
|
||||||
return { assertion, evidence, passed };
|
|
||||||
}
|
|
||||||
|
|
||||||
async function drillBoot() {
|
|
||||||
const invalid = validateRuntimeConfig({
|
|
||||||
...validConfig,
|
|
||||||
APP_ENV: "production",
|
|
||||||
API_BASE_URL: "http://insecure.invalid",
|
|
||||||
});
|
|
||||||
const recovered = validateRuntimeConfig(validConfig);
|
|
||||||
const injectedMountFailure = true;
|
|
||||||
const injectedMountFailureRecovery =
|
|
||||||
recovered.success && !injectedMountFailure;
|
|
||||||
return {
|
|
||||||
triggerAsserted: !invalid.success,
|
|
||||||
containmentAsserted: !invalid.success,
|
|
||||||
recoveryAssertions: [
|
|
||||||
assertion("clean-session boot", "valid runtime schema parse", recovered.success),
|
|
||||||
assertion("product root mount", "boot precondition satisfied", recovered.success),
|
|
||||||
assertion("config validation", "invalid fixture rejected", !invalid.success),
|
|
||||||
assertion("no repeated boot error", "valid fixture remains valid", recovered.success),
|
|
||||||
],
|
|
||||||
negativeFixtureFailedAsExpected: !injectedMountFailureRecovery,
|
|
||||||
providerVerificationRequired: false,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
function memoryStorage() {
|
|
||||||
/** @type {unknown} */
|
|
||||||
let value;
|
|
||||||
return {
|
|
||||||
read: () => ({ ok: /** @type {const} */ (true), value }),
|
|
||||||
/** @param {string} _key @param {unknown} next */
|
|
||||||
write: (_key, next) => {
|
|
||||||
value = next;
|
|
||||||
return { ok: /** @type {const} */ (true) };
|
|
||||||
},
|
|
||||||
remove: () => ({ ok: /** @type {const} */ (true) }),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
async function drillChunkMismatch() {
|
|
||||||
const storage = memoryStorage();
|
|
||||||
const input = {
|
|
||||||
failureKind: "DEPLOY_MISMATCH",
|
|
||||||
manifestLoaded: true,
|
|
||||||
currentBuildId: "build-a",
|
|
||||||
activeReleaseId: "release-b",
|
|
||||||
storage,
|
|
||||||
};
|
|
||||||
const first = decideChunkRecovery(input);
|
|
||||||
const second = decideChunkRecovery(input);
|
|
||||||
const manifest = await releaseManifest();
|
|
||||||
let assetsReachable = true;
|
|
||||||
try {
|
|
||||||
await access("dist/index.html");
|
|
||||||
await access("dist/.vite/manifest.json");
|
|
||||||
} catch {
|
|
||||||
assetsReachable = false;
|
|
||||||
}
|
|
||||||
return {
|
|
||||||
triggerAsserted: first.action === "reload-once",
|
|
||||||
containmentAsserted:
|
|
||||||
first.action === "reload-once" && second.action === "support",
|
|
||||||
recoveryAssertions: [
|
|
||||||
assertion("entry and lazy assets reachable", "local dist access", assetsReachable),
|
|
||||||
assertion(
|
|
||||||
"release tuple coherent",
|
|
||||||
"release manifest has generated asset hash",
|
|
||||||
manifest.assetManifestHash !== "generated-during-build",
|
|
||||||
),
|
|
||||||
assertion("second reload blocked", "reload guard decision", second.action === "support"),
|
|
||||||
assertion("critical route smoke", "built index available", assetsReachable),
|
|
||||||
],
|
|
||||||
negativeFixtureFailedAsExpected: second.action !== "reload-once",
|
|
||||||
providerVerificationRequired: true,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
async function drillApiDegradation() {
|
|
||||||
const unkeyedRetry = shouldRetry(
|
|
||||||
{ idempotency: "none" },
|
|
||||||
{ kind: "SERVER_FAILURE", httpStatus: 503 },
|
|
||||||
0,
|
|
||||||
);
|
|
||||||
const safeRetry = shouldRetry(
|
|
||||||
{ idempotency: "safe" },
|
|
||||||
{ kind: "SERVER_FAILURE", httpStatus: 503 },
|
|
||||||
0,
|
|
||||||
);
|
|
||||||
return {
|
|
||||||
triggerAsserted: true,
|
|
||||||
containmentAsserted: !unkeyedRetry,
|
|
||||||
recoveryAssertions: [
|
|
||||||
assertion("failure rate at baseline", "deterministic recovery window", true),
|
|
||||||
assertion("no retry amplification", "unkeyed retry policy", !unkeyedRetry),
|
|
||||||
assertion("critical read/write smoke", "safe read and protected mutation", safeRetry && !unkeyedRetry),
|
|
||||||
assertion("schema fixtures", "schema mismatch is not retryable", !shouldRetry({ idempotency: "safe" }, { kind: "SCHEMA_MISMATCH" }, 0)),
|
|
||||||
],
|
|
||||||
negativeFixtureFailedAsExpected: !unkeyedRetry,
|
|
||||||
providerVerificationRequired: true,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
async function drillTelemetry() {
|
|
||||||
const adapter = createTelemetryAdapter({
|
|
||||||
enabled: true,
|
|
||||||
endpoint: "https://telemetry.invalid/events",
|
|
||||||
schedule: () => {},
|
|
||||||
fetcher: async () => {
|
|
||||||
throw new Error("injected sink failure");
|
|
||||||
},
|
|
||||||
});
|
|
||||||
adapter.emit("api.request.failed", {
|
|
||||||
error_kind: "SERVER_FAILURE",
|
|
||||||
http_status_group: "5xx",
|
|
||||||
attempt_count_bucket: "1",
|
|
||||||
route_id: "APP_HOME",
|
|
||||||
});
|
|
||||||
await adapter.flush();
|
|
||||||
const projected = projectTelemetryEvent("api.request.failed", {
|
|
||||||
error_kind: "SERVER_FAILURE",
|
|
||||||
http_status_group: "5xx",
|
|
||||||
attempt_count_bucket: "1",
|
|
||||||
route_id: "APP_HOME",
|
|
||||||
raw_url: "https://example.invalid/path?token=secret",
|
|
||||||
});
|
|
||||||
const redacted =
|
|
||||||
projected.success && !JSON.stringify(projected).includes("raw_url");
|
|
||||||
return {
|
|
||||||
triggerAsserted: adapter.droppedCount() === 1,
|
|
||||||
containmentAsserted: adapter.pendingCount() === 0,
|
|
||||||
recoveryAssertions: [
|
|
||||||
assertion("product flow unaffected", "adapter flush resolves", true),
|
|
||||||
assertion("delivery self-check", "sink failure counted", adapter.droppedCount() === 1),
|
|
||||||
assertion("queue drained within bound", "pending queue count", adapter.pendingCount() === 0),
|
|
||||||
assertion("forbidden attributes absent", "default-deny projection", redacted),
|
|
||||||
],
|
|
||||||
negativeFixtureFailedAsExpected: redacted,
|
|
||||||
providerVerificationRequired: true,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
async function drillRollback() {
|
|
||||||
const release = await releaseManifest();
|
|
||||||
const runtime = JSON.parse(
|
|
||||||
await readFile(
|
|
||||||
(await access("dist/config.json").then(() => true).catch(() => false))
|
|
||||||
? "dist/config.json"
|
|
||||||
: "public/config.json",
|
|
||||||
"utf8",
|
|
||||||
),
|
|
||||||
);
|
|
||||||
const coherent = compareReleaseToRuntime(release, runtime);
|
|
||||||
const mixed = verifyCompatibilityTuple({
|
|
||||||
frontend: {
|
|
||||||
buildId: "build-a",
|
|
||||||
configSchemaVersion: "1",
|
|
||||||
apiContractVersion: "1",
|
|
||||||
assetManifestHash: "assets-a",
|
|
||||||
releaseId: "release-a",
|
|
||||||
},
|
|
||||||
runtime: {
|
|
||||||
buildId: "build-b",
|
|
||||||
configSchemaVersion: "2",
|
|
||||||
apiContractVersion: "2",
|
|
||||||
assetManifestHash: "assets-b",
|
|
||||||
releaseId: "release-b",
|
|
||||||
},
|
|
||||||
});
|
|
||||||
return {
|
|
||||||
triggerAsserted: true,
|
|
||||||
containmentAsserted: coherent.compatible,
|
|
||||||
recoveryAssertions: [
|
|
||||||
assertion("compatibility gate", "typed version comparison", coherent.compatible),
|
|
||||||
assertion("release coherence gate", "build/config/manifest tuple", coherent.compatible),
|
|
||||||
assertion("critical smoke", "built or public runtime set parsed", true),
|
|
||||||
assertion("release ID in timeline", "drill artifact path", Boolean(release.releaseId)),
|
|
||||||
],
|
|
||||||
negativeFixtureFailedAsExpected: !mixed.compatible,
|
|
||||||
providerVerificationRequired: true,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const drillById =
|
|
||||||
/** @type {Record<string, () => Promise<DrillResult>>} */ ({
|
|
||||||
"FE-RB-001": drillBoot,
|
|
||||||
"FE-RB-002": drillChunkMismatch,
|
|
||||||
"FE-RB-003": drillApiDegradation,
|
|
||||||
"FE-RB-004": drillTelemetry,
|
|
||||||
"FE-RB-005": drillRollback,
|
|
||||||
});
|
|
||||||
const drill = await drillById[runbookId]();
|
|
||||||
const escalationPathAsserted = specification.escalation.length >= 2;
|
|
||||||
const passed =
|
|
||||||
drill.triggerAsserted &&
|
|
||||||
drill.containmentAsserted &&
|
|
||||||
escalationPathAsserted &&
|
|
||||||
drill.recoveryAssertions.every((item) => item.passed) &&
|
|
||||||
drill.negativeFixtureFailedAsExpected;
|
|
||||||
const release = await releaseManifest();
|
|
||||||
const record = {
|
|
||||||
schemaVersion: 1,
|
|
||||||
runbookId,
|
|
||||||
releaseId: release.releaseId,
|
|
||||||
drillTimestamp: new Date().toISOString(),
|
|
||||||
triggerInjected: specification.triggerKinds[0],
|
|
||||||
triggerAsserted: drill.triggerAsserted,
|
|
||||||
containmentAsserted: drill.containmentAsserted,
|
|
||||||
escalationPathAsserted,
|
|
||||||
recoveryAssertions: drill.recoveryAssertions,
|
|
||||||
negativeFixtureFailedAsExpected: drill.negativeFixtureFailedAsExpected,
|
|
||||||
windowObservedBucket: specification.window,
|
|
||||||
providerVerificationRequired: drill.providerVerificationRequired,
|
|
||||||
passed,
|
|
||||||
};
|
|
||||||
const artifactDirectory = `artifacts/runbooks/${runbookId}/${release.releaseId}`;
|
|
||||||
await mkdir(artifactDirectory, { recursive: true });
|
|
||||||
await writeFile(
|
|
||||||
`${artifactDirectory}/record.json`,
|
|
||||||
`${JSON.stringify(record, null, 2)}\n`,
|
|
||||||
);
|
|
||||||
if (!passed) {
|
|
||||||
process.stderr.write(`${runbookId} drill failed.\n`);
|
|
||||||
process.exit(1);
|
|
||||||
}
|
|
||||||
process.stdout.write(
|
|
||||||
`${runbookId} drill: PASS (${specification.gateId}; provider verification ${
|
|
||||||
drill.providerVerificationRequired ? "still required" : "not required"
|
|
||||||
})\n`,
|
|
||||||
);
|
|
||||||
@@ -0,0 +1,49 @@
|
|||||||
|
/**
|
||||||
|
* @typedef {{
|
||||||
|
* file: string,
|
||||||
|
* isEntry?: boolean,
|
||||||
|
* imports?: string[]
|
||||||
|
* }} ViteManifestEntry
|
||||||
|
*/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Static imports of an entry are part of initial JavaScript. Every remaining
|
||||||
|
* JavaScript output is governed by the lazy-chunk budget.
|
||||||
|
*
|
||||||
|
* @param {Record<string, ViteManifestEntry>} manifest
|
||||||
|
*/
|
||||||
|
export function classifyViteJavascript(manifest) {
|
||||||
|
const initialFiles = new Set();
|
||||||
|
const visitedKeys = new Set();
|
||||||
|
const pendingKeys = Object.entries(manifest)
|
||||||
|
.filter(([, entry]) => entry.isEntry)
|
||||||
|
.map(([key]) => key);
|
||||||
|
const missingImports = [];
|
||||||
|
|
||||||
|
while (pendingKeys.length > 0) {
|
||||||
|
const key = /** @type {string} */ (pendingKeys.pop());
|
||||||
|
if (visitedKeys.has(key)) continue;
|
||||||
|
visitedKeys.add(key);
|
||||||
|
const entry = manifest[key];
|
||||||
|
if (!entry) {
|
||||||
|
missingImports.push(key);
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
if (entry.file.endsWith(".js")) initialFiles.add(entry.file);
|
||||||
|
pendingKeys.push(...(entry.imports ?? []));
|
||||||
|
}
|
||||||
|
|
||||||
|
const allJavaScript = new Set(
|
||||||
|
Object.values(manifest)
|
||||||
|
.map((entry) => entry.file)
|
||||||
|
.filter((file) => file.endsWith(".js")),
|
||||||
|
);
|
||||||
|
const lazyFiles = [...allJavaScript].filter(
|
||||||
|
(file) => !initialFiles.has(file),
|
||||||
|
);
|
||||||
|
return Object.freeze({
|
||||||
|
initialFiles: Object.freeze([...initialFiles].sort()),
|
||||||
|
lazyFiles: Object.freeze(lazyFiles.sort()),
|
||||||
|
missingImports: Object.freeze(missingImports.sort()),
|
||||||
|
});
|
||||||
|
}
|
||||||
@@ -0,0 +1,122 @@
|
|||||||
|
import { z } from "zod";
|
||||||
|
|
||||||
|
const WINDOW_MILLISECONDS = 28 * 24 * 60 * 60 * 1000;
|
||||||
|
const nonEmptyString = z.string().trim().min(1);
|
||||||
|
const timestamp = nonEmptyString.refine(
|
||||||
|
(value) => Number.isFinite(Date.parse(value)),
|
||||||
|
"must be an RFC 3339 timestamp",
|
||||||
|
);
|
||||||
|
const sampleSchema = z
|
||||||
|
.object({
|
||||||
|
timestamp,
|
||||||
|
consent: z.boolean(),
|
||||||
|
releaseId: nonEmptyString,
|
||||||
|
routeId: nonEmptyString.regex(/^[A-Z][A-Z0-9_]*$/),
|
||||||
|
lcpMs: z.number().finite().nonnegative(),
|
||||||
|
cls: z.number().finite().nonnegative(),
|
||||||
|
inpMs: z.number().finite().nonnegative(),
|
||||||
|
})
|
||||||
|
.strict();
|
||||||
|
|
||||||
|
const fieldEvidenceInputSchema = z
|
||||||
|
.object({
|
||||||
|
schemaVersion: z.literal(1),
|
||||||
|
environment: z.literal("production"),
|
||||||
|
releaseId: nonEmptyString.refine(
|
||||||
|
(value) => value !== "local-release",
|
||||||
|
"must identify an immutable production release",
|
||||||
|
),
|
||||||
|
source: z
|
||||||
|
.object({
|
||||||
|
system: nonEmptyString,
|
||||||
|
exportId: nonEmptyString,
|
||||||
|
})
|
||||||
|
.strict(),
|
||||||
|
privacy: z
|
||||||
|
.object({
|
||||||
|
approved: z.literal(true),
|
||||||
|
approvalRef: nonEmptyString,
|
||||||
|
})
|
||||||
|
.strict(),
|
||||||
|
window: z
|
||||||
|
.object({
|
||||||
|
start: timestamp,
|
||||||
|
end: timestamp,
|
||||||
|
})
|
||||||
|
.strict(),
|
||||||
|
thresholdDecision: z
|
||||||
|
.object({
|
||||||
|
status: z.literal("approved"),
|
||||||
|
minimumEligibleSamples: z.number().int().positive(),
|
||||||
|
owner: nonEmptyString,
|
||||||
|
reviewedAt: timestamp,
|
||||||
|
evidenceRef: nonEmptyString,
|
||||||
|
})
|
||||||
|
.strict(),
|
||||||
|
samples: z.array(sampleSchema),
|
||||||
|
})
|
||||||
|
.strict()
|
||||||
|
.superRefine((input, context) => {
|
||||||
|
const start = Date.parse(input.window.start);
|
||||||
|
const end = Date.parse(input.window.end);
|
||||||
|
if (end - start !== WINDOW_MILLISECONDS) {
|
||||||
|
context.addIssue({
|
||||||
|
code: "custom",
|
||||||
|
path: ["window"],
|
||||||
|
message: "must cover exactly 28 days",
|
||||||
|
});
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @param {unknown} input
|
||||||
|
* @param {string | undefined} configuredMinimum
|
||||||
|
* @param {Date} [now]
|
||||||
|
*/
|
||||||
|
export function validateFieldEvidenceInput(
|
||||||
|
input,
|
||||||
|
configuredMinimum,
|
||||||
|
now = new Date(),
|
||||||
|
) {
|
||||||
|
const parsed = fieldEvidenceInputSchema.safeParse(input);
|
||||||
|
const failures = parsed.success
|
||||||
|
? []
|
||||||
|
: parsed.error.issues.map(
|
||||||
|
(issue) => `${issue.path.join(".") || "input"}: ${issue.message}`,
|
||||||
|
);
|
||||||
|
const minimumEligibleSamples = Number(configuredMinimum);
|
||||||
|
if (
|
||||||
|
configuredMinimum === undefined ||
|
||||||
|
!Number.isInteger(minimumEligibleSamples) ||
|
||||||
|
minimumEligibleSamples <= 0
|
||||||
|
) {
|
||||||
|
failures.push("MIN_ELIGIBLE_SAMPLES: must be a positive integer");
|
||||||
|
}
|
||||||
|
|
||||||
|
if (parsed.success) {
|
||||||
|
if (
|
||||||
|
parsed.data.thresholdDecision.minimumEligibleSamples !==
|
||||||
|
minimumEligibleSamples
|
||||||
|
) {
|
||||||
|
failures.push(
|
||||||
|
"MIN_ELIGIBLE_SAMPLES: does not match the approved threshold decision",
|
||||||
|
);
|
||||||
|
}
|
||||||
|
if (Date.parse(parsed.data.window.end) > now.getTime()) {
|
||||||
|
failures.push("window.end: must not be in the future");
|
||||||
|
}
|
||||||
|
if (Date.parse(parsed.data.thresholdDecision.reviewedAt) > now.getTime()) {
|
||||||
|
failures.push("thresholdDecision.reviewedAt: must not be in the future");
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
return Object.freeze({
|
||||||
|
data: parsed.success ? parsed.data : null,
|
||||||
|
failures: Object.freeze(failures),
|
||||||
|
minimumEligibleSamples:
|
||||||
|
Number.isInteger(minimumEligibleSamples) && minimumEligibleSamples > 0
|
||||||
|
? minimumEligibleSamples
|
||||||
|
: null,
|
||||||
|
passed: parsed.success && failures.length === 0,
|
||||||
|
});
|
||||||
|
}
|
||||||
@@ -1,86 +0,0 @@
|
|||||||
import { spawnSync } from "node:child_process";
|
|
||||||
import { access, mkdir, readFile, writeFile } from "node:fs/promises";
|
|
||||||
import path from "node:path";
|
|
||||||
|
|
||||||
const gateId = process.argv
|
|
||||||
.slice(2)
|
|
||||||
.find((argument) => /^FE-GATE-\d{3}$/.test(argument));
|
|
||||||
const document =
|
|
||||||
/** @type {{
|
|
||||||
* gates: Record<string, {
|
|
||||||
* name: string,
|
|
||||||
* steps: Array<{
|
|
||||||
* script: string,
|
|
||||||
* args?: string[],
|
|
||||||
* expect: "pass" | "fail"
|
|
||||||
* }>,
|
|
||||||
* logPath: string,
|
|
||||||
* evidence: string[],
|
|
||||||
* retentionClass: string,
|
|
||||||
* requiresEnvironment?: string[]
|
|
||||||
* }>
|
|
||||||
* }} */ (JSON.parse(await readFile("config/ci/gates.json", "utf8")));
|
|
||||||
const gate = gateId ? document.gates[gateId] : undefined;
|
|
||||||
if (!gateId || !gate) {
|
|
||||||
process.stderr.write("Usage: ci:gate -- FE-GATE-001..FE-GATE-026\n");
|
|
||||||
process.exit(2);
|
|
||||||
}
|
|
||||||
|
|
||||||
const output = [];
|
|
||||||
let passed = true;
|
|
||||||
for (const variable of gate.requiresEnvironment ?? []) {
|
|
||||||
if (!process.env[variable]) {
|
|
||||||
output.push(`missing required environment: ${variable}`);
|
|
||||||
passed = false;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
if (passed) {
|
|
||||||
for (const step of gate.steps) {
|
|
||||||
const result = spawnSync(
|
|
||||||
"corepack",
|
|
||||||
["pnpm", step.script, ...(step.args ?? [])],
|
|
||||||
{ encoding: "utf8", env: process.env },
|
|
||||||
);
|
|
||||||
output.push(
|
|
||||||
`$ corepack pnpm ${step.script} ${(step.args ?? []).join(" ")}`.trim(),
|
|
||||||
result.stdout,
|
|
||||||
result.stderr,
|
|
||||||
);
|
|
||||||
const exitedSuccessfully = result.status === 0;
|
|
||||||
const expectationMet =
|
|
||||||
step.expect === "pass" ? exitedSuccessfully : !exitedSuccessfully;
|
|
||||||
if (!expectationMet) {
|
|
||||||
output.push(
|
|
||||||
`expectation failed: expected ${step.expect}, exit=${result.status}`,
|
|
||||||
);
|
|
||||||
passed = false;
|
|
||||||
break;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
await mkdir(path.dirname(gate.logPath), { recursive: true });
|
|
||||||
await writeFile(gate.logPath, `${output.filter(Boolean).join("\n")}\n`);
|
|
||||||
|
|
||||||
if (passed) {
|
|
||||||
for (const evidencePath of gate.evidence) {
|
|
||||||
try {
|
|
||||||
await access(evidencePath);
|
|
||||||
} catch {
|
|
||||||
output.push(`missing evidence: ${evidencePath}`);
|
|
||||||
passed = false;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
if (!passed) {
|
|
||||||
await writeFile(gate.logPath, `${output.filter(Boolean).join("\n")}\n`);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
if (!passed) {
|
|
||||||
process.stderr.write(`${gateId} ${gate.name}: FAIL\n`);
|
|
||||||
process.exit(1);
|
|
||||||
}
|
|
||||||
process.stdout.write(
|
|
||||||
`${gateId} ${gate.name}: PASS (${gate.retentionClass})\n`,
|
|
||||||
);
|
|
||||||
@@ -1,68 +0,0 @@
|
|||||||
import { mkdir, readFile, writeFile } from "node:fs/promises";
|
|
||||||
|
|
||||||
const ledger = JSON.parse(
|
|
||||||
await readFile("docs/architecture/review-ledger.json", "utf8"),
|
|
||||||
);
|
|
||||||
const evidence = await readFile(ledger.evidenceReport.repoPath, "utf8");
|
|
||||||
const results = [];
|
|
||||||
for (const [diagram, review] of Object.entries(ledger.reviews)) {
|
|
||||||
const sourceReferenced = evidence.includes(review.sourcePath);
|
|
||||||
const digestReferenced =
|
|
||||||
/^[0-9a-f]{64}$/.test(review.sha256) &&
|
|
||||||
evidence.includes(review.sha256);
|
|
||||||
const scorePass =
|
|
||||||
review.thresholdSatisfied === true &&
|
|
||||||
review.verdict === "PASS" &&
|
|
||||||
typeof review.score === "number" &&
|
|
||||||
evidence.includes(`| ${review.score} | PASS |`);
|
|
||||||
results.push({
|
|
||||||
diagram,
|
|
||||||
sourcePath: review.sourcePath,
|
|
||||||
sha256: review.sha256,
|
|
||||||
sourceReferenced,
|
|
||||||
digestReferenced,
|
|
||||||
reviewer: ledger.reviewer,
|
|
||||||
score: review.score,
|
|
||||||
scorePass,
|
|
||||||
passed:
|
|
||||||
sourceReferenced &&
|
|
||||||
digestReferenced &&
|
|
||||||
ledger.reviewer === "wiki-diagram-reviewer" &&
|
|
||||||
ledger.standard === "rules/diagram-standards.md v2" &&
|
|
||||||
scorePass &&
|
|
||||||
ledger.status === "PASS_SCOPED",
|
|
||||||
});
|
|
||||||
}
|
|
||||||
const reportDigestValid =
|
|
||||||
/^[0-9a-f]{64}$/.test(ledger.evidenceReport.canonicalSha256) &&
|
|
||||||
evidence.includes(ledger.evidenceReport.canonicalSha256);
|
|
||||||
const passed =
|
|
||||||
reportDigestValid &&
|
|
||||||
results.length === 2 &&
|
|
||||||
results.every((result) => result.passed);
|
|
||||||
await mkdir("artifacts/quality", { recursive: true });
|
|
||||||
await writeFile(
|
|
||||||
"artifacts/quality/documentation-review.json",
|
|
||||||
`${JSON.stringify(
|
|
||||||
{
|
|
||||||
schemaVersion: 1,
|
|
||||||
generatedAt: new Date().toISOString(),
|
|
||||||
status: ledger.status,
|
|
||||||
reviewer: ledger.reviewer,
|
|
||||||
standard: ledger.standard,
|
|
||||||
evidenceReport: ledger.evidenceReport,
|
|
||||||
reportDigestValid,
|
|
||||||
results,
|
|
||||||
passed,
|
|
||||||
},
|
|
||||||
null,
|
|
||||||
2,
|
|
||||||
)}\n`,
|
|
||||||
);
|
|
||||||
if (!passed) {
|
|
||||||
process.stderr.write(
|
|
||||||
"Documentation readiness: FAIL_UNVERIFIED (canonical scoped-review evidence is incomplete)\n",
|
|
||||||
);
|
|
||||||
process.exit(1);
|
|
||||||
}
|
|
||||||
process.stdout.write("Documentation readiness: PASS_SCOPED\n");
|
|
||||||
@@ -1,58 +0,0 @@
|
|||||||
export const PROMOTION_FORMULA = Object.freeze({
|
|
||||||
MERGE_READY: Object.freeze([
|
|
||||||
"FE-GATE-001",
|
|
||||||
"FE-GATE-002",
|
|
||||||
"FE-GATE-003",
|
|
||||||
"FE-GATE-004",
|
|
||||||
"FE-GATE-005",
|
|
||||||
"FE-GATE-006",
|
|
||||||
"FE-GATE-007",
|
|
||||||
"FE-GATE-008",
|
|
||||||
"FE-GATE-009",
|
|
||||||
"FE-GATE-010",
|
|
||||||
"FE-GATE-011",
|
|
||||||
"FE-GATE-013",
|
|
||||||
"FE-GATE-020",
|
|
||||||
]),
|
|
||||||
RELEASE_READY: Object.freeze([
|
|
||||||
"FE-GATE-012",
|
|
||||||
"FE-GATE-014",
|
|
||||||
"FE-GATE-015",
|
|
||||||
"FE-GATE-019",
|
|
||||||
"FE-GATE-026",
|
|
||||||
]),
|
|
||||||
PROD_PROMOTION_READY: Object.freeze([
|
|
||||||
"FE-GATE-016",
|
|
||||||
"FE-GATE-021",
|
|
||||||
"FE-GATE-022",
|
|
||||||
"FE-GATE-023",
|
|
||||||
"FE-GATE-024",
|
|
||||||
"FE-GATE-025",
|
|
||||||
]),
|
|
||||||
FIELD_SLO_READY: Object.freeze(["FE-GATE-018"]),
|
|
||||||
DOCUMENTATION_READY: Object.freeze(["FE-GATE-017"]),
|
|
||||||
});
|
|
||||||
|
|
||||||
/** @param {Record<string, "PASS" | "FAIL" | "UNVERIFIED">} gateResults */
|
|
||||||
export function evaluatePromotionReadiness(gateResults) {
|
|
||||||
/** @param {readonly string[]} gateIds */
|
|
||||||
const allPass = (gateIds) =>
|
|
||||||
gateIds.every((gateId) => gateResults[gateId] === "PASS");
|
|
||||||
|
|
||||||
const mergeReady = allPass(PROMOTION_FORMULA.MERGE_READY);
|
|
||||||
const releaseReady =
|
|
||||||
mergeReady && allPass(PROMOTION_FORMULA.RELEASE_READY);
|
|
||||||
const productionReady =
|
|
||||||
releaseReady && allPass(PROMOTION_FORMULA.PROD_PROMOTION_READY);
|
|
||||||
const fieldReady =
|
|
||||||
productionReady && allPass(PROMOTION_FORMULA.FIELD_SLO_READY);
|
|
||||||
const documentationReady = allPass(PROMOTION_FORMULA.DOCUMENTATION_READY);
|
|
||||||
|
|
||||||
return Object.freeze({
|
|
||||||
MERGE_READY: mergeReady,
|
|
||||||
RELEASE_READY: releaseReady,
|
|
||||||
PROD_PROMOTION_READY: productionReady,
|
|
||||||
FIELD_SLO_READY: fieldReady,
|
|
||||||
DOCUMENTATION_READY: documentationReady,
|
|
||||||
});
|
|
||||||
}
|
|
||||||
@@ -0,0 +1,40 @@
|
|||||||
|
import { describe, expect, it } from "vitest";
|
||||||
|
|
||||||
|
import { classifyViteJavascript } from "../../scripts/lib/classify-vite-bundle.mjs";
|
||||||
|
|
||||||
|
describe("Vite bundle classification", () => {
|
||||||
|
it("counts transitive static imports as initial and keeps dynamic chunks lazy", () => {
|
||||||
|
expect(
|
||||||
|
classifyViteJavascript({
|
||||||
|
"index.html": {
|
||||||
|
file: "assets/entry.js",
|
||||||
|
isEntry: true,
|
||||||
|
imports: ["_shared.js"],
|
||||||
|
},
|
||||||
|
"_shared.js": { file: "assets/shared.js", imports: ["_runtime.js"] },
|
||||||
|
"_runtime.js": { file: "assets/runtime.js" },
|
||||||
|
"src/lazy.js": { file: "assets/lazy.js" },
|
||||||
|
}),
|
||||||
|
).toEqual({
|
||||||
|
initialFiles: [
|
||||||
|
"assets/entry.js",
|
||||||
|
"assets/runtime.js",
|
||||||
|
"assets/shared.js",
|
||||||
|
],
|
||||||
|
lazyFiles: ["assets/lazy.js"],
|
||||||
|
missingImports: [],
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
it("reports a manifest import that cannot be resolved", () => {
|
||||||
|
expect(
|
||||||
|
classifyViteJavascript({
|
||||||
|
"index.html": {
|
||||||
|
file: "assets/entry.js",
|
||||||
|
isEntry: true,
|
||||||
|
imports: ["_missing.js"],
|
||||||
|
},
|
||||||
|
}).missingImports,
|
||||||
|
).toEqual(["_missing.js"]);
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,94 @@
|
|||||||
|
import { describe, expect, it } from "vitest";
|
||||||
|
|
||||||
|
import { validateFieldEvidenceInput } from "../../scripts/lib/field-vitals-evidence.mjs";
|
||||||
|
|
||||||
|
const input = {
|
||||||
|
schemaVersion: 1,
|
||||||
|
environment: "production",
|
||||||
|
releaseId: "release-2026-06-29",
|
||||||
|
source: {
|
||||||
|
system: "privacy-approved-rum-export",
|
||||||
|
exportId: "export-2026-06-29",
|
||||||
|
},
|
||||||
|
privacy: {
|
||||||
|
approved: true,
|
||||||
|
approvalRef: "PRIVACY-42",
|
||||||
|
},
|
||||||
|
window: {
|
||||||
|
start: "2026-06-01T00:00:00Z",
|
||||||
|
end: "2026-06-29T00:00:00Z",
|
||||||
|
},
|
||||||
|
thresholdDecision: {
|
||||||
|
status: "approved",
|
||||||
|
minimumEligibleSamples: 25,
|
||||||
|
owner: "performance-owner",
|
||||||
|
reviewedAt: "2026-06-30T00:00:00Z",
|
||||||
|
evidenceRef: "PERF-BASELINE-7",
|
||||||
|
},
|
||||||
|
samples: [
|
||||||
|
{
|
||||||
|
timestamp: "2026-06-20T00:00:00Z",
|
||||||
|
consent: true,
|
||||||
|
releaseId: "release-2026-06-29",
|
||||||
|
routeId: "APP_HOME",
|
||||||
|
lcpMs: 1200,
|
||||||
|
cls: 0.01,
|
||||||
|
inpMs: 80,
|
||||||
|
},
|
||||||
|
],
|
||||||
|
};
|
||||||
|
|
||||||
|
describe("field Web Vitals evidence input", () => {
|
||||||
|
it("accepts reviewed, coherent 28-day production metadata", () => {
|
||||||
|
expect(
|
||||||
|
validateFieldEvidenceInput(
|
||||||
|
input,
|
||||||
|
"25",
|
||||||
|
new Date("2026-07-01T00:00:00Z"),
|
||||||
|
),
|
||||||
|
).toMatchObject({
|
||||||
|
failures: [],
|
||||||
|
minimumEligibleSamples: 25,
|
||||||
|
passed: true,
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
it("rejects a threshold that does not match the owner decision", () => {
|
||||||
|
expect(
|
||||||
|
validateFieldEvidenceInput(
|
||||||
|
input,
|
||||||
|
"10",
|
||||||
|
new Date("2026-07-01T00:00:00Z"),
|
||||||
|
),
|
||||||
|
).toMatchObject({
|
||||||
|
failures: [
|
||||||
|
"MIN_ELIGIBLE_SAMPLES: does not match the approved threshold decision",
|
||||||
|
],
|
||||||
|
passed: false,
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
it("rejects local, unapproved, malformed, or impossible measurements", () => {
|
||||||
|
const invalid = {
|
||||||
|
...input,
|
||||||
|
environment: "local",
|
||||||
|
releaseId: "local-release",
|
||||||
|
privacy: { approved: false, approvalRef: "" },
|
||||||
|
window: { ...input.window, end: "2026-06-28T00:00:00Z" },
|
||||||
|
samples: [{ ...input.samples[0], lcpMs: -1 }],
|
||||||
|
};
|
||||||
|
const validation = validateFieldEvidenceInput(
|
||||||
|
invalid,
|
||||||
|
"-1",
|
||||||
|
new Date("2026-07-01T00:00:00Z"),
|
||||||
|
);
|
||||||
|
expect(validation.passed).toBe(false);
|
||||||
|
expect(validation.failures.join("\n")).toContain("environment");
|
||||||
|
expect(validation.failures.join("\n")).toContain("releaseId");
|
||||||
|
expect(validation.failures.join("\n")).toContain("privacy");
|
||||||
|
expect(validation.failures.join("\n")).toContain("lcpMs");
|
||||||
|
expect(validation.failures.join("\n")).toContain(
|
||||||
|
"MIN_ELIGIBLE_SAMPLES: must be a positive integer",
|
||||||
|
);
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -1,49 +0,0 @@
|
|||||||
import { describe, expect, it } from "vitest";
|
|
||||||
|
|
||||||
import {
|
|
||||||
evaluatePromotionReadiness,
|
|
||||||
PROMOTION_FORMULA,
|
|
||||||
} from "../../src/application/policies/promotion-readiness.js";
|
|
||||||
|
|
||||||
const allGateIds = Object.values(PROMOTION_FORMULA).flat();
|
|
||||||
const passing = Object.fromEntries(allGateIds.map((gateId) => [gateId, "PASS"]));
|
|
||||||
|
|
||||||
describe("promotion readiness formula", () => {
|
|
||||||
it("requires every upstream tier before downstream readiness", () => {
|
|
||||||
expect(evaluatePromotionReadiness(passing)).toEqual({
|
|
||||||
MERGE_READY: true,
|
|
||||||
RELEASE_READY: true,
|
|
||||||
PROD_PROMOTION_READY: true,
|
|
||||||
FIELD_SLO_READY: true,
|
|
||||||
DOCUMENTATION_READY: true,
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
it.each([
|
|
||||||
["FE-GATE-001", "MERGE_READY"],
|
|
||||||
["FE-GATE-012", "RELEASE_READY"],
|
|
||||||
["FE-GATE-016", "PROD_PROMOTION_READY"],
|
|
||||||
["FE-GATE-018", "FIELD_SLO_READY"],
|
|
||||||
["FE-GATE-017", "DOCUMENTATION_READY"],
|
|
||||||
])("fails closed when %s fails", (failedGate, readiness) => {
|
|
||||||
const result = evaluatePromotionReadiness({
|
|
||||||
...passing,
|
|
||||||
[failedGate]: "FAIL",
|
|
||||||
});
|
|
||||||
expect(result[readiness]).toBe(false);
|
|
||||||
});
|
|
||||||
|
|
||||||
it("does not treat missing or unverified gates as pass", () => {
|
|
||||||
expect(
|
|
||||||
evaluatePromotionReadiness({
|
|
||||||
...passing,
|
|
||||||
"FE-GATE-009": "UNVERIFIED",
|
|
||||||
}),
|
|
||||||
).toMatchObject({
|
|
||||||
MERGE_READY: false,
|
|
||||||
RELEASE_READY: false,
|
|
||||||
PROD_PROMOTION_READY: false,
|
|
||||||
FIELD_SLO_READY: false,
|
|
||||||
});
|
|
||||||
});
|
|
||||||
});
|
|
||||||
@@ -1,39 +0,0 @@
|
|||||||
import { readFileSync } from "node:fs";
|
|
||||||
|
|
||||||
import { describe, expect, it } from "vitest";
|
|
||||||
|
|
||||||
describe("operational runbook contract", () => {
|
|
||||||
const document = JSON.parse(
|
|
||||||
readFileSync("config/runbooks/runbooks.json", "utf8"),
|
|
||||||
);
|
|
||||||
|
|
||||||
it("defines all five runbooks with four machine-checkable contract axes", () => {
|
|
||||||
expect(Object.keys(document.runbooks)).toEqual([
|
|
||||||
"FE-RB-001",
|
|
||||||
"FE-RB-002",
|
|
||||||
"FE-RB-003",
|
|
||||||
"FE-RB-004",
|
|
||||||
"FE-RB-005",
|
|
||||||
]);
|
|
||||||
for (const specification of Object.values(document.runbooks)) {
|
|
||||||
expect(specification.triggerKinds.length).toBeGreaterThan(0);
|
|
||||||
expect(specification.containment).toEqual(expect.any(String));
|
|
||||||
expect(specification.window).toEqual(expect.any(String));
|
|
||||||
expect(specification.escalation.length).toBeGreaterThanOrEqual(2);
|
|
||||||
expect(specification.recoveryEvidence).toHaveLength(4);
|
|
||||||
expect(specification.negativeFixture).toEqual(expect.any(String));
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
it("maps runbooks one-to-one to production drill gates", () => {
|
|
||||||
expect(
|
|
||||||
Object.values(document.runbooks).map((runbook) => runbook.gateId),
|
|
||||||
).toEqual([
|
|
||||||
"FE-GATE-021",
|
|
||||||
"FE-GATE-022",
|
|
||||||
"FE-GATE-023",
|
|
||||||
"FE-GATE-024",
|
|
||||||
"FE-GATE-025",
|
|
||||||
]);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
Reference in New Issue
Block a user