360 lines
14 KiB
Python
360 lines
14 KiB
Python
"""Mechanical validation of `profil/kandidat.md` against build-brief 5.1.
|
|
|
|
The brief's own instruction about this file is the one that shapes everything
|
|
here: *"The operator will supply an existing kandidat.md. Treat its structure
|
|
as the contract and validate against it rather than regenerating it."* So this
|
|
module reports; it never rewrites, and it never refuses a profile for being
|
|
richer than the contract anticipated. A missing required key is an error that
|
|
names the key path. Anything the contract has no opinion about is a warning.
|
|
|
|
Reading the operator's real file on 2026-09-04 produced seven places where the
|
|
file and 5.1 disagree. Six are settled here, and each is a decision rather
|
|
than an accident, so each is written down where it was taken.
|
|
|
|
**1. A mapping value that has to hold several items.** The operator accepts
|
|
two employment forms and rejects two more, but the Step 4 grammar allows only
|
|
a scalar beneath a mapping key (`child := " " KEY ":" SP scalar`). Three ways
|
|
out were open: widen the grammar, lift the key to the top level, or make the
|
|
separator a contract. The separator wins. Widening the grammar puts a second
|
|
parse mode on the hand-rolled parser that sits on the hard-filter path, and
|
|
that parser's whole value is that it is small enough to hold in the head
|
|
(risk H7); lifting the key changes the shape of a file the operator already
|
|
wrote. So: **a comma splits a scalar into items, a slash splits one item into
|
|
alternatives, and whitespace inside an alternative is a phrase.** One rule,
|
|
applied identically to `ansettelsesform.aksepterer`, `ansettelsesform.avviser`
|
|
and each entry of `absolutte_nei` -- which is why `åremål/engasjement, vikariat`
|
|
reads as two rejected forms, the first of which has two names, and
|
|
`personalansvar / linjeledelse` reads as one no with two names. The rule costs
|
|
the ability to write a comma inside an employment form; no employment form has
|
|
one.
|
|
|
|
**2. Keys outside 5.1.** An unknown key is a warning, never an error: the
|
|
operator owns this file. But a key that scoring actually reads must not look
|
|
like the typo it is otherwise indistinguishable from, so the small set in
|
|
:data:`HONORERTE_UTVIDELSER` warns *and says it is honoured*.
|
|
|
|
**3.** Travel time as a soft filter is scoring's decision, and lives in
|
|
`scripts/vurdering.py`.
|
|
|
|
**4. `vurderer_flytting` is a word, not a boolean.** The grammar has no
|
|
boolean -- `render` refuses one outright -- so the value is the word the
|
|
operator wrote, and the check is a closed word set rather than a type.
|
|
|
|
**5. An explicitly unmeasured outcome.** 5.1 asks each signature project for a
|
|
measurable outcome. One of the operator's has none, and says so instead of
|
|
offering an estimate. Structure is checked here; whether an outcome is real is
|
|
judgement, and a validator that demanded a number would be a validator that
|
|
rewarded inventing one. So the body is checked for its sections and their
|
|
order, and for nothing inside them.
|
|
|
|
**6. `senioritet.min` / `.maks` are free text.** 5.1 gives no enum, and the
|
|
operator's values are `seniorrådgiver` and `fagdirektør/sjefsarkitekt`. The
|
|
ordering that makes the seniority filter more than decorative is a rank table,
|
|
which belongs to scoring; here the words are carried through intact.
|
|
|
|
**7. A breadth bullet need not name a skill.** Nothing in this module parses
|
|
inside a section, which is exactly what lets *"teknologisk breddeforståelse og
|
|
intuisjon"* stand as breadth.
|
|
"""
|
|
|
|
import json
|
|
|
|
from jobbsok_lib import frontmatter, paths
|
|
|
|
#: Body sections from build-brief 5.1, in the order the contract requires.
|
|
SEKSJONER = (
|
|
"Kjerne",
|
|
"Kompetanse",
|
|
"Retning",
|
|
"Signaturprosjekter",
|
|
"Kjente svakheter",
|
|
"Formuleringer som virker",
|
|
"Profilgap",
|
|
)
|
|
|
|
#: Required frontmatter keys from 5.1. A tuple of leaves means a nested block;
|
|
#: `None` means a top-level scalar or list. Seventeen keys counting leaves.
|
|
PAAKREVD = (
|
|
("oppdatert", None),
|
|
("geografi", ("base", "maks_reisetid_min", "hjemmekontor_min_dager", "vurderer_flytting")),
|
|
("lonn", ("gulv_nok", "onsket_nok", "kommentar")),
|
|
("ansettelsesform", ("aksepterer", "avviser")),
|
|
("absolutte_nei", None),
|
|
("senioritet", ("min", "maks")),
|
|
)
|
|
|
|
#: Keys whose value the hard filters compare numerically.
|
|
HELTALL = ("geografi.maks_reisetid_min", "geografi.hjemmekontor_min_dager",
|
|
"lonn.gulv_nok", "lonn.onsket_nok")
|
|
|
|
#: The closed word set for `geografi.vurderer_flytting` (divergence 4).
|
|
FLYTTING_ORD = ("ja", "nei", "kanskje")
|
|
|
|
#: Scoring criteria, and the weights shipped when the profile names none.
|
|
#: Percentages so the vector reads as a distribution at a glance; scoring
|
|
#: normalises by the sum, so any non-negative integers would do.
|
|
STANDARDVEKTER = {
|
|
"fagomrade": 40,
|
|
"oppgavetype": 30,
|
|
"teknologi": 20,
|
|
"selskapstype": 10,
|
|
}
|
|
|
|
#: Keys outside 5.1 that scoring nevertheless reads, with the reason. Warned
|
|
#: about like any unknown key, but named as honoured so an extension the
|
|
#: plugin acts on is distinguishable from a misspelling it ignores.
|
|
HONORERTE_UTVIDELSER = {
|
|
"arbeidssteder": (
|
|
"utenfor 5.1, men lest av vurdering: en eksplisitt liste over "
|
|
"akseptable arbeidssteder gjoer reisetid til en advarsel for disse "
|
|
"stedene"
|
|
),
|
|
}
|
|
|
|
#: Additive key from operator decision 14.3.
|
|
VEKTNOKKEL = "vekter"
|
|
|
|
KJENTE_TOPPNOKLER = tuple(key for key, _ in PAAKREVD) + (VEKTNOKKEL,)
|
|
|
|
FENCE = "```"
|
|
|
|
|
|
def validate(text):
|
|
"""Validate a `kandidat.md` document and return the report.
|
|
|
|
Malformed frontmatter is not a finding -- it is
|
|
:class:`~jobbsok_lib.frontmatter.FrontmatterError`, raised with the
|
|
offending line number, because a document that did not parse has no
|
|
findings to report on.
|
|
"""
|
|
meta, body = frontmatter.parse(text)
|
|
feil = []
|
|
advarsler = []
|
|
|
|
_sjekk_paakrevde(meta, feil)
|
|
_sjekk_typer(meta, feil)
|
|
_sjekk_ukjente(meta, advarsler)
|
|
|
|
seksjoner = _seksjoner(body)
|
|
_sjekk_seksjoner(seksjoner, feil)
|
|
|
|
vekter, kilde = _vekter(meta, feil, advarsler)
|
|
|
|
return {
|
|
"gyldig": not feil,
|
|
"feil": feil,
|
|
"advarsler": advarsler,
|
|
"seksjoner": seksjoner,
|
|
"senioritet": _blokk(meta, "senioritet"),
|
|
"ansettelsesform": {
|
|
felt: del_skalar(_blokk(meta, "ansettelsesform").get(felt))
|
|
for felt in ("aksepterer", "avviser")
|
|
},
|
|
"absolutte_nei": [del_alternativer(item) for item in _liste(meta, "absolutte_nei")],
|
|
"arbeidssteder": _liste(meta, "arbeidssteder"),
|
|
"vekter_kilde": kilde,
|
|
"vekter": vekter,
|
|
}
|
|
|
|
|
|
def validate_file(root, *parts):
|
|
"""Validate the profile at ``parts`` under ``root``, via ``paths.safe_join``."""
|
|
meta, body = frontmatter.read(root, *parts)
|
|
return validate(frontmatter.render(meta, body))
|
|
|
|
|
|
def report_json(report):
|
|
"""Render a report as the canonical JSON the golden files hold.
|
|
|
|
``ensure_ascii=False``: the report quotes the operator's own words back,
|
|
and `Sørdal` escaped to a `\\u00f8` sequence is no longer the word that
|
|
was written.
|
|
"""
|
|
return json.dumps(report, ensure_ascii=False, indent=2) + "\n"
|
|
|
|
|
|
def del_skalar(value):
|
|
"""Split a scalar into items, then each item into alternatives.
|
|
|
|
The divergence-1 contract: comma between items, slash between alternatives
|
|
for the same item. ``None`` and the empty string are an empty list, not a
|
|
list holding an empty name.
|
|
"""
|
|
if value is None:
|
|
return []
|
|
items = [part.strip() for part in str(value).split(",")]
|
|
return [del_alternativer(item) for item in items if item]
|
|
|
|
|
|
def del_alternativer(item):
|
|
"""Split one item on slashes into its alternative spellings."""
|
|
parts = [part.strip() for part in str(item).split("/")]
|
|
return [part for part in parts if part]
|
|
|
|
|
|
def normaliser(text):
|
|
"""Fold a term for comparison: lowercase ASCII, hyphen-separated tokens.
|
|
|
|
Goes through :func:`paths.slug` so the Norwegian folds are defined in one
|
|
place. A term that folds to nothing (punctuation only) returns ``""``
|
|
rather than raising, because a comparison helper must not be the thing
|
|
that stops a run.
|
|
"""
|
|
try:
|
|
return paths.slug(text)
|
|
except ValueError:
|
|
return ""
|
|
|
|
|
|
def _sjekk_paakrevde(meta, feil):
|
|
for key, leaves in PAAKREVD:
|
|
if key not in meta:
|
|
_feil(feil, key, "paakrevd noekkel mangler (build-brief 5.1)")
|
|
# Naming only the block would leave the operator guessing which
|
|
# leaves to write, so every leaf is named too.
|
|
for leaf in leaves or ():
|
|
_feil(feil, "%s.%s" % (key, leaf), "paakrevd noekkel mangler (build-brief 5.1)")
|
|
continue
|
|
if leaves is None:
|
|
continue
|
|
blokk = meta[key]
|
|
if not isinstance(blokk, dict):
|
|
_feil(feil, key, "forventet et nestet kart med %s" % ", ".join(leaves))
|
|
continue
|
|
for leaf in leaves:
|
|
if leaf not in blokk:
|
|
_feil(feil, "%s.%s" % (key, leaf), "paakrevd noekkel mangler (build-brief 5.1)")
|
|
|
|
|
|
def _sjekk_typer(meta, feil):
|
|
for path in HELTALL:
|
|
key, leaf = path.split(".")
|
|
blokk = meta.get(key)
|
|
if not isinstance(blokk, dict) or leaf not in blokk:
|
|
continue
|
|
if not isinstance(blokk[leaf], int):
|
|
_feil(feil, path,
|
|
"hardfiltrene sammenligner denne numerisk; %r er ikke et heltall"
|
|
% (blokk[leaf],))
|
|
|
|
if isinstance(meta.get("absolutte_nei"), dict):
|
|
_feil(feil, "absolutte_nei", "forventet en liste, fikk et kart")
|
|
|
|
geografi = meta.get("geografi")
|
|
if isinstance(geografi, dict) and "vurderer_flytting" in geografi:
|
|
verdi = geografi["vurderer_flytting"]
|
|
if str(verdi).strip().lower() not in FLYTTING_ORD:
|
|
_feil(feil, "geografi.vurderer_flytting",
|
|
"grammatikken har ingen boolsk verdi; skriv %s (fikk %r)"
|
|
% (", ".join(FLYTTING_ORD), verdi))
|
|
|
|
|
|
def _sjekk_ukjente(meta, advarsler):
|
|
for key in meta:
|
|
if key in KJENTE_TOPPNOKLER:
|
|
continue
|
|
if key in HONORERTE_UTVIDELSER:
|
|
_advarsel(advarsler, key, HONORERTE_UTVIDELSER[key])
|
|
else:
|
|
_advarsel(advarsler, key,
|
|
"utenfor build-brief 5.1; beholdt, men ingenting leser den")
|
|
|
|
for key, leaves in PAAKREVD:
|
|
if leaves is None or not isinstance(meta.get(key), dict):
|
|
continue
|
|
for leaf in meta[key]:
|
|
if leaf not in leaves:
|
|
_advarsel(advarsler, "%s.%s" % (key, leaf),
|
|
"utenfor build-brief 5.1; beholdt, men ingenting leser den")
|
|
|
|
|
|
def _seksjoner(body):
|
|
"""The `## ` headings of the body, in document order.
|
|
|
|
Only level two counts: the real profile opens with an H1 title and uses H3
|
|
inside Kompetanse, Retning and Signaturprosjekter, and neither is a
|
|
section in the 5.1 sense. Fenced blocks are skipped so a `##` inside an
|
|
example is prose, not structure.
|
|
"""
|
|
funnet = []
|
|
inne_i_fence = False
|
|
for line in body.split("\n"):
|
|
if line.startswith(FENCE):
|
|
inne_i_fence = not inne_i_fence
|
|
continue
|
|
if inne_i_fence:
|
|
continue
|
|
if line.startswith("## ") and not line.startswith("### "):
|
|
funnet.append(line[3:].strip())
|
|
return funnet
|
|
|
|
|
|
def _sjekk_seksjoner(funnet, feil):
|
|
mangler = [name for name in SEKSJONER if name not in funnet]
|
|
if mangler:
|
|
_feil(feil, "seksjoner",
|
|
"mangler seksjon(er): %s (build-brief 5.1)" % ", ".join(mangler))
|
|
|
|
kjente = [name for name in funnet if name in SEKSJONER]
|
|
forventet = [name for name in SEKSJONER if name in funnet]
|
|
if kjente != forventet:
|
|
_feil(feil, "seksjoner",
|
|
"seksjonene staar i rekkefoelgen %s; 5.1 krever %s"
|
|
% (" > ".join(kjente), " > ".join(forventet)))
|
|
|
|
|
|
def _vekter(meta, feil, advarsler):
|
|
if VEKTNOKKEL not in meta:
|
|
return dict(STANDARDVEKTER), "default"
|
|
|
|
raw = meta[VEKTNOKKEL]
|
|
if not isinstance(raw, dict):
|
|
_feil(feil, VEKTNOKKEL, "forventet et kart over kriterium: vekt")
|
|
return dict(STANDARDVEKTER), "default"
|
|
|
|
vekter = {}
|
|
for kriterium in STANDARDVEKTER:
|
|
if kriterium not in raw:
|
|
_advarsel(advarsler, "%s.%s" % (VEKTNOKKEL, kriterium),
|
|
"ikke oppgitt; bruker standardvekten %d"
|
|
% STANDARDVEKTER[kriterium])
|
|
vekter[kriterium] = STANDARDVEKTER[kriterium]
|
|
continue
|
|
verdi = raw[kriterium]
|
|
if not isinstance(verdi, int) or verdi < 0:
|
|
_feil(feil, "%s.%s" % (VEKTNOKKEL, kriterium),
|
|
"vekten maa vaere et heltall >= 0, fikk %r" % (verdi,))
|
|
vekter[kriterium] = STANDARDVEKTER[kriterium]
|
|
continue
|
|
vekter[kriterium] = verdi
|
|
|
|
for kriterium in raw:
|
|
if kriterium not in STANDARDVEKTER:
|
|
_advarsel(advarsler, "%s.%s" % (VEKTNOKKEL, kriterium),
|
|
"ukjent kriterium; scoringen leser det ikke")
|
|
|
|
if sum(vekter.values()) == 0:
|
|
_feil(feil, VEKTNOKKEL, "summen av vektene er 0; da har ingen kriterier vekt")
|
|
return vekter, "profil"
|
|
|
|
|
|
def _blokk(meta, key):
|
|
verdi = meta.get(key)
|
|
return dict(verdi) if isinstance(verdi, dict) else {}
|
|
|
|
|
|
def _liste(meta, key):
|
|
verdi = meta.get(key)
|
|
if isinstance(verdi, list):
|
|
return list(verdi)
|
|
if verdi is None or isinstance(verdi, dict):
|
|
return []
|
|
return [verdi]
|
|
|
|
|
|
def _feil(feil, nokkel, melding):
|
|
feil.append({"nokkel": nokkel, "melding": melding})
|
|
|
|
|
|
def _advarsel(advarsler, nokkel, melding):
|
|
advarsler.append({"nokkel": nokkel, "melding": melding})
|