portal/docs/lint.md

The lint

The iris over a site. A content push is an incoming wormhole; nothing comes through until it checks out.

portal iris --path questions                      # a local checkout
portal lint --repo https://project.uhhm.no/uhhm/questions
portal lint replay --path questions --nats nats://127.0.0.1:14222

portal iris is the lint's name, after the iris that keeps bad content out of the portal; portal lint runs the same thing, so workflows that already call it keep working.

It was its own binary, iris, until portal 0.6: the same code, released as portal's twin. Now it is the portal binary's lint command, so a content repo's CI downloads the release and runs it:

      - run: |
          curl -sfL "https://project.uhhm.no/uhhm/portal/releases/download/$PORTAL_RELEASE/portal-x86_64-linux" -o portal
          chmod +x portal && ./portal lint --path questions

check loads a content repo exactly the way the running site does, validates it (every action lands on a page, every transition is one the state machine allows, every recorded bucket is read back somewhere), and then holds it to the business needs the repo declares in needs.yaml, when it has one:

• a path of submissions gets each kind of visitor's answer into the bucket it names, within a submission and required-field budget;
• the handling group holds a desk over that bucket, and every finished state is reachable through the buttons it (and any also_moved_by group) offers; no record strands on the way;
• every stage the business named is a state of the machine, and each working stage can follow the one before it;
• across each bucket, whichever need brought a record in: every state is somewhere a record can get to, no state a record gets to holds it with no way on (before done or after), every declared move is a button, a visitor's own link or a clock (a move nobody offers warns), no desk is gated to one group on the page and another on its list, and every mail goes out from a state records reach and names only fields the forms collect.

Every finding says what to change and where: the missing { from, to, label } and the desk page it goes on, the group that already has the button, or the edge aggregates.yaml lacks. A schema error no longer hides the needs findings - both are printed, so one round can fix them together.

--findings <out.jsonl> writes the same findings one JSON object per line: id, level (fail/warn), code, scope (need, bucket, or repo for a schema error), need (the need's id, or the bucket's name), subject (the state, the move as from>to, or the page), message and fix. The file is written empty when the content is clean. id hashes scope, need, code and subject and nothing of the wording, so the same gap keeps its id from one run to the next: a trainer can tell what a round closed, what is still open and what it broke. The codes:

code
schema	content the site would refuse to load
need-duplicate, persona-unknown-need	needs.yaml itself
entry-missing, entry-gated, entry-no-responsible	the page a visitor arrives on
path-missing, path-closed, path-over-budget, path-no-action	getting the answer recorded
machine-missing, desk-missing, desk-gated-twice	who works the bucket
done-unknown, done-unreachable, success-not-done	finishing a case
stage-unknown, stage-unreachable, stage-order	the business's own stages
state-unreached, strand, edge-unoffered	every state and move of the bucket
mail-unreachable, mail-unknown-field	what a state mails

A need marked planned warns instead of failing. Exit status is the verdict, so a content repo's CI is one line.

Beyond the verdict, check exports what a trainer needs to grade the wording: --needs-tasks writes the personas as typed choice tasks (--skim for headings only), --needs-score grades an engine's answers, and --needs-sim writes a resolved model of the whole site. portal lint replay runs simulated cases through the site's real aggregate engine on a throwaway JetStream and reports every bucket by state; --report-only takes the same scorecard from a live site's buckets. See Training a site for what sits around those.

Matching the site

The lint is the site: portal lint and portal serve are one binary built from one source, so a content shape the site reads is a shape the lint knows, at the same version. A content repo pins PORTAL_RELEASE to what its site runs and lints with that release's portal. The IRIS_RELEASE pins from before portal 0.6 keep working against the iris releases that exist; nothing new is published there.