@cobre-npm/portal-widgets

@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

Testing

pnpm test runs three things in order, and any one of them going red fails the build:

1. The suite — Vitest over src/**/*.{test,spec}.ts.
2. Coverage — enforced against the thresholds in coverage-floor.json.
3. 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.