@cobre-npm/portal-widgets
Embeddable Vue 3 widgets for Cobre's portal, published to npm and consumed by the portal shell and
by any other host app. vue and vue-i18n are external — the host provides them.
Scripts
| Script | What it does |
|---|---|
pnpm dev | Vite dev harness (src/main.ts) |
pnpm build | Build the publishable library into dist/ + emit types into dist/types/ |
pnpm test | The whole gate: the suite, coverage against the floor, and the ratchet |
pnpm lint | Lint & auto-fix with ESLint |
Testing
pnpm test runs three things in order, and any one of them going red fails the build:
- The suite — Vitest over
src/**/*.{test,spec}.ts. - Coverage — enforced against the thresholds in
coverage-floor.json. - The ratchet —
scripts/check-invariants.mjs, which compares the floor against the base ref.
src/repo-invariants.test.ts guards the shape of the gate rather than its numbers: that the
thresholds are read from coverage-floor.json and not inlined, that all four metrics are declared,
that no whole widget directory gets excluded to shrink the denominator, and that the test script
still invokes a real runner with no --passWithNoTests. Without it the gate can be defeated without
touching a number the ratchet watches.
The lane covers src/**/*.ts minus tests, type-only modules, enums, locales, mocks, constants,
barrels and the dev entry. The .vue components are deliberately not in the denominator: unlike
ds-v3 this package has no story lane, so there is no binary render gate to pair a percentage with,
and folding the untested components into one number would measure the absence of a render lane
rather than the logic (ADR-0008).
The coverage floor ratchets
coverage-floor.json is a floor, not a target. It holds what the repo measured the day the gate
was switched on (2026-09-17), not 95%, because there is no retroactive backfill — a gate nobody can
adopt on day one is a gate nobody turns on.
It may only rise. scripts/check-invariants.mjs fails when any number in it drops below the value on
the base ref, when a metric is removed altogether, or when the base ref does not resolve — a ratchet
that silently did not run is indistinguishable from one that passed, which is the defect this whole
gate exists to remove. Lowering the floor in the same commit that
breaks it is exactly what the ratchet exists to prevent.
When you add tests and coverage rises, raise the floor in the same PR. That is the whole mechanism.
Outside CI the ratchet is a no-op unless you give it a base ref:
node scripts/check-invariants.mjs --base origin/trunk
Where this gate is enforced
The pipeline is not in this repo. It lives in Cobre-Colombia/circleci-library at
pipes/npm/config-frontend-libraries.yml, whose build_unit job runs
eval "CI=true ${TEST_CMD:-npm test}".
This package has no .env file in that repo's config/frontend-libraries-project-overrides/, so
build_unit falls through to its default npm test — and that default is the gate. The absence
is deliberate rather than an oversight: the pipe needs no override for this step to run, and an
override here could only weaken the command the package already defines for itself.
If one is ever added, it must not carry a TEST_CMD of the vitest ... --passWithNoTests shape.
That is exactly what neutralised util-ds: the step ran, reported success, and could never fail.
CI=true is also what switches the ratchet on: without it check-invariants.mjs has no base ref and
exits 0.
Architecture
See CLAUDE.md for the widget layout, the export surface, the localization pattern and the code style rules.