Errors#

Every exception Scenet raises, under one root.

scenet.errors#

Every exception Scenet raises, in one place.

A library that scatters its exception types across the modules that happen to raise them forces callers to import from six places to write one except clause. Every error Scenet raises is a ScenetError, and every one a caller can catch by name is imported from scenet, so that

except ScenetError:

catches every error a public function raises for bad input, a bad file or a call that cannot be honoured, and nothing that is not Scenet’s: a ValueError from elsewhere in your program goes past it.

Two things are not covered, by design:

  • Building a model yourself – PanelIR(...), CameraSpec(...) – validates it as pydantic does, and raises pydantic’s ValidationError, a ValueError. Scenet’s own frontends turn that into a PanelSyntaxError with a location.

  • A bug in Scenet – an invariant of its own that fails – is not your input’s fault, and is not dressed up as if it were.

The hierarchy answers the question a caller actually has, which is whose fault is it:

ScenetError
|-- SourceError        the document is wrong -- report it to whoever wrote the panel
|   |-- PanelSyntaxError, ScriptSyntaxError, CompositionError
|   `-- CoreSyntaxError    a Panel or Page Core document that does not read back
|-- SolverError        the document is fine, but no layout satisfies it
|   `-- LayoutError, BalloonPlacementError, SfxPlacementError
|-- AssetError         a puppet or a font is missing or malformed
|   |-- UnknownPuppetError, UnknownPoseError, UnknownExpressionError
|   `-- MalformedAssetError
|-- FileReadError      a file a call names cannot be read
|   `-- MissingFileError
|-- RenderError        a renderer was not handed what the drawing needs
`-- UnknownActorError  a Panel Core asked for an actor it does not hold

Each also inherits the built-in exception a caller would have reached for before this module existed – SourceError is a ValueError, UnknownPuppetError a KeyError, MissingFileError a FileNotFoundError – so pre-existing except ValueError handlers keep working unchanged.

exception scenet.errors.RuleViolationError[source]#

Bases: ValueError

A named rule, broken at a known place in the document.

Raised inside pydantic validators rather than out of them. pydantic wraps whatever a validator raises into its own ValidationError, and for a model-level validator it records the location as () – the whole document – because a validator has no way to say which field it was unhappy about. That is accurate and useless: the two checks that matter most here, check_references_resolve and check_ordering_is_consistent, both knew the exact path and had nowhere to put it, so every such diagnostic read at <root>.

pydantic keeps the exception object it caught, under ctx["error"], so a subclass carrying extra attributes survives validation intact and can be recovered on the other side. That is the whole trick.

A plain ValueError so that a validator raising one behaves exactly as before for anybody not looking for the extra attributes. It deliberately does not inherit ScenetError: it never escapes validation as itself – pydantic catches it and re-raises its own ValidationError – so putting it in that hierarchy would promise a except ScenetError clause could catch it, which it cannot.

rule#

Identifier from the catalogue in scenet.diagnostics. Stable across releases, because a ruleId that moves breaks every alert that referenced it.

loc#

Path to the offending value, in pydantic’s loc form – string keys and integer indices, as in ("script", 0, "say", "by").

__init__(message, *, rule, loc=())[source]#

Build the violation.

Parameters:
  • message (str) – What is wrong, phrased for whoever wrote the document.

  • rule (str) – Catalogue identifier for the rule that was broken.

  • loc (tuple[str | int, ...]) – Path to the offending value. Empty means the document as a whole.

scenet.diagnostics#

What scenet check reports: every rule by its id, and a document’s findings as SARIF.

Machine-readable diagnostics, in SARIF.

A compiler failure is prose on stderr. That is right for a person and useless for anything else: CI cannot annotate a pull request with it, an editor cannot draw a squiggle under it, and an agent repairing its own output cannot tell which of five things went wrong.

This matters more here than the published JSON Schema does. The checks that catch what a generator actually gets wrong are model_validator methods in scenet.ir – every actor id resolving to a cast member, the left_of/right_of graph being acyclic – and neither is expressible in JSON Schema at all. Structured diagnostics are what make a generate/validate/repair loop work, whether the thing doing the repairing is a person pasting an error back into a chat window or a tool call.

Why SARIF

SARIF 2.1.0 is an OASIS standard. GCC emits it under -fdiagnostics-format=sarif, MSVC and Clang emit it, and GitHub code scanning ingests it directly. A bespoke {"errors": [...]} shape would be one nobody else can read.

2.1.0, not 2.2. 2.2 is still a draft, and 2.1.0 documents are forward-consumable by 2.2 processors, so there is nothing to gain by chasing it.

Hand-built, not `sarif-python-om`. The document is one run, one driver and a handful of results; the object model would be a runtime dependency and a licence-gate entry to build a few nested dicts. cli.py already assembles JSON Schema by hand for the same reason. If the emitted subset grows past a page of code, revisit it.

Determinism

Byte-identical output for identical input is a project non-negotiable, and it reaches this module: results come back in source order, rules are emitted sorted by id, and partialFingerprints are content-derived rather than positional – so a finding keeps its identity when a comment is added above it, and an alert is not re-raised as new on every unrelated edit.

scenet.diagnostics.COMPILE_NOTES: dict[Literal['camera-retreated', 'curved-tail', 'cropped-mouth', 'cropped-marks', 'inset-covers-face', 'slant-cuts-face', 'italic-stand-in', 'bold-italic-stand-in'], Rule] = {'bold-italic-stand-in': Rule(summary='No bold italic face is named, so another face stands in for it', description='A stressed word, written between underscores, is lettered in bold italic. When `lettering.font` names no bold italic face, stressed words are set in its italic face, or its regular one if it names no italic either -- so the stress is not seen.', help='Name the bold italic face, as `bold_italic:` in `lettering.font`.', level='note'), 'camera-retreated': Rule(summary='The camera stepped back so the cast would fit across the panel', description="A shot type is a crop landmark and a headroom, in head-heights, so a close-up of one person is a fixed scale. Two people side by side at that scale can be wider than the panel. Rather than crop somebody out, the camera retreats -- keeps the shot's crop line and headroom, at a smaller scale -- and the note says by how much, as a share of the framing that was asked for.", help='Widen the panel, ask for a looser shot, or stage fewer people in it; or accept it, if a slightly looser shot is fine.', level='note'), 'cropped-marks': Rule(summary="A character's marks run off the panel at this framing", description='Emanata -- plewds, motion lines, a question mark -- are drawn outside the head, and the camera frames by the body: it makes no room for them, which is what keeps them from ever moving anybody. A tight shot can therefore crop them, and a mark that vanished without a word would be a surprise.', help='Ask for a looser shot, or give the marks to somebody they fit around.', level='note'), 'cropped-mouth': Rule(summary="A speaking figure's mouth is cropped out of the panel by the picture's fit", description="`fit: cover` fills the panel with a supplied picture and crops what overhangs. When that crops the mouth of a figure who speaks, the balloon's tail cannot reach it, so it stops on the frame, aimed at where the mouth is.", help='Write `fit: contain`, which shows the whole picture, or reshape the panel.', level='note'), 'curved-tail': Rule(summary="A balloon's tail bends around a face", description="A tail runs from its balloon to the speaker's mouth, or to the frame for a voice from off panel. When a straight one would cross somebody's face, it bends around it instead. Nothing is wrong, but a bent tail is usually a sign that the balloon sits far from its speaker, or that the panel is crowded.", help="Let the balloon sit on its speaker's side -- drop its `prefer`, or ask for the zone nearer the speaker -- or give the panel more room.", level='note'), 'inset-covers-face': Rule(summary='An inset is drawn over a face', description="An inset is set into a corner of its panel and drawn over it. The panel's art is staged and framed as if the inset were not there -- only its lettering keeps clear -- so an inset can cover a face as easily as a patch of sky.", help="Set the inset into another corner, make it smaller, or frame the panel so that nobody's face is in that corner.", level='note'), 'italic-stand-in': Rule(summary='No italic face is named, so the regular face stands in for it', description="Every caption but a `spoken` one is lettered in italic. `lettering.font` names the faces a document is lettered in; when it names a regular face and no italic, those captions are set in the regular face. It is the document's own face that stands in, not the shipped italic: a family mixing two typefaces would not be one family.", help='Name the italic face beside the regular one, as `italic:` in `lettering.font`.', level='note'), 'slant-cuts-face': Rule(summary='A slanted gutter cuts across a face', description='A slanted tier leans the gutters between its panels. Each panel is staged and framed in its bounding box as usual and then cut to its outline, as a margin would cut it; the camera does not know the cut is there, so it can fall across a face.', help='Lean the tier less, or frame the shot so the face is clear of the cut: a looser shot, or the face further from the slanted side.', level='note')}#

Every note the compiler gives, keyed by its stable name: what it means and what to do.

A compile note is not a finding of scenet check: the document is valid, and the compiler decided something it did not literally ask for – a camera that stepped back, a tail that bends. scenet build prints it as a note: line, and CompileResult.compile_notes gives it with its name. The names are as stable as the rules’ ids.

scenet.diagnostics.RULES: dict[str, Rule] = {'artwork-contract': Rule(summary="A picture's artwork contract cannot be read", description="A panel that casts a figure a supplied picture draws reads the picture's artwork contract, beside it and named after it: `art/p01.png` has its contract at `art/p01.art.yaml`. It must be there, and be YAML holding the picture's `size`, its `figures` and its `keep_out` regions, in the picture's own pixels. The size must be the picture's, every point must lie on the picture, and every region must be a simple polygon. A fault inside the contract is reported in it, when the document was checked as a file.", help="Put the contract beside its picture with the picture's name, measure it on this picture, and check it against `scenet schema --artwork`. The debug overlay (`scenet build --debug`) draws what it declares over the panel.", level='error'), 'balloon-placement': Rule(summary='A balloon or caption has no legal position', description='Every candidate position covered a face, left the panel, overlapped a box already placed, or would have broken reading order.', help='Widen the panel, shorten the line, or split it across two panels.', level='error'), 'caption-speaker': Rule(summary='A caption that is not `spoken` names a speaker', description="`by` names who says an off-panel line, so only a `spoken` caption has one. A `locale` box states a place and a time, a `monologue` is a voice nobody hears and an `editorial` one is the writer's: none of them is said by anybody, so a speaker named on one is a mistake rather than a field to ignore.", help='Remove `by`, or make the caption `kind: spoken` if somebody off panel says it.', level='error'), 'composition': Rule(summary='An `over:` chain cannot be resolved', description='A panel inherits from one that does not exist, or the chain is cyclic and so has no fixed point to resolve to.', help='Check the panel name in `over:` and that the chain terminates.', level='error'), 'conflicting-cast': Rule(summary='A cast member is a puppet and a figure, or a cast mixes the two', description="A cast member is a puppet Scenet poses (`reference`) or a figure a supplied picture draws (`figure`), never both. Nobody poses or places a figure, so a puppet's `pose`, `expression`, `marks`, `at` and `facing` do not apply to one. A cast is all puppets or all figures, since staging and the camera would place a puppet over a painted face they cannot see; and one figure is one person, played by one cast member.", help="Keep `reference` or `figure`. On a member inherited from a scene's defaults, write the other as `null`, and the same for a puppet's keys.", level='error'), 'conflicting-setting': Rule(summary='A setting says what is behind the cast twice', description='A place *is* a mass list -- the preset expands into exactly what an author could have written -- so naming one and listing the other asks two questions at once, and the compiler will not guess which was meant. A supplied `image` is a whole backdrop of its own, so it stands alone too: beside a place, masses, or a horizon, which only says where masses meet the ground.', help='Keep one of the place, the masses and the image. On a panel that inherits one, write it as `null` to leave it out. What each place expands into is at https://creatoan.github.io/scenet/reference/language/setting.html#settingplace.', level='error'), 'dropped-relation': Rule(summary='A shared staging relation does not apply in a panel its actor is left out of', description="A comic script's `ALICE (OP)` leaves Alice out of that panel: she is in the scene, not in the frame. `cast: {alice: null}` leaves her out of a panel that would otherwise inherit her, in YAML or in a script's `@cast:`. A relation stated for every panel -- `ALICE left_of BOB`, `ALICE looking_at BOB` -- cannot hold where she is not drawn, so it is left out of that panel. A note, since that changes what the panel stages: Bob is placed, and looks, without her. All but `BOB looking_at ALICE` while she speaks from off panel there: Bob turns toward her side of the frame, and nothing is noted.", help='Nothing to do if that is what the panel means; otherwise draw her in it.', level='note'), 'duplicate-key': Rule(summary='A key is written twice in one mapping', description="YAML requires every key in a mapping to be unique, but the parser Scenet reads it with builds the document anyway and keeps only the last value -- so a panel, a cast member or a pose written twice would lose the first without a word, and the rest would compile. A merge key's override (`<<: *base`, then the key again) is not a repeat. In a comic script, the same goes for a directive written twice in one panel, and for an `@script:` directive, which would replace the panel's cues.", help='Delete or rename one of the two; the message says which lines they are on.', level='error'), 'duplicate-panel': Rule(summary='Two panels in a comic script have the same name', description='Panels are named by their PANEL heading, and by their PAGE heading as well when panel numbers start again on each page. Two panels that still share a name -- PANEL 1 twice on one page, or twice with no PAGE heading between them -- cannot both be kept, and dropping one without a word would lose whatever it held.', help='Number the panels straight through, or put a PAGE heading before each page whose numbering starts again.', level='error'), 'figure-staging': Rule(summary='Staging or a camera for figures a picture draws', description='The artist already framed, placed and staged everybody a picture draws, so a staging relation naming a figure has nothing to place, and a `camera` on a panel whose cast is all figures has nothing to frame: the shot is whatever the picture shows. Either would be a key with no effect, and this language reports slips.', help='Remove the relation, or the `camera`. On a panel that inherits a camera, write `camera: null`.', level='error'), 'font-file': Rule(summary='A declared font file cannot be read', description='`lettering.font` names font files, read relative to the folder the document is in. Each must be a relative path, the file must be there, and it must be a TrueType or OpenType font with a Unicode character map, since lettering is measured against it. A document compiled from text with no file behind it has no folder, and so can name no font.', help="Check the path against the document's folder, write it relative to that folder, or point it at a .ttf or .otf file.", level='error'), 'image-file': Rule(summary='A supplied picture cannot be read', description='`setting.image` names a picture to draw behind the cast, read relative to the folder the document is in. It must be a relative path written with `/`, the file must be there, and it must be a PNG or JPEG whose header gives its size and whose EXIF does not turn it -- renderers disagree on obeying that. A document compiled from text with no file behind it has no folder, and so can name no picture unless the picture is sent with it.', help="Check the path against the document's folder, write it relative to that folder, or save the picture as a PNG or JPEG with its pixels upright.", level='error'), 'internal': Rule(summary='The compiler failed in a way it does not have a rule for', description='A Scenet error reached the checker without a more specific rule. Worth reporting: either the document found something genuinely new, or a rule is missing from the catalogue.', help='Please open an issue with the document that produced it.', level='error'), 'invalid-field': Rule(summary='A field has the wrong shape or value', description='The key is known but what it holds is not what the language accepts there -- a string where a number belongs, or a value outside the allowed set.', help="Check the field's type and permitted values on its card, from https://creatoan.github.io/scenet/reference/language/keys.html.", level='error'), 'layout': Rule(summary="No layout satisfies the panel's constraints", description='Nothing is misspelled and nothing is missing, but the panel as described has no solution -- most often two actors each required to be left of the other. Panel bounds are deliberately not required, so a merely crowded panel is not this.', help='Relax or remove a conflicting staging relation.', level='error'), 'looks-like-dialogue': Rule(summary='A line in a comic script is set like dialogue but is not read as dialogue', description="A cue with nothing said under it, or a name in capitals with a line under it where nothing is spoken -- before the first PANEL heading, which Dark Horse's format opens with the writer's name and address. Read as written, nothing is lost, but a line meant as dialogue would not be lettered, so it is pointed out.", help='If it is dialogue, put the line under its cue, inside a panel; if not, ignore it.', level='note'), 'missing-field': Rule(summary='A required field is missing', description='The value is required and was not supplied.', help='Add the field. `scenet schema` prints the full shape the compiler accepts.', level='error'), 'not-a-mapping': Rule(summary='The document is not a mapping', description='A panel document is a mapping of top-level keys -- panel, camera, cast, staging, script. A list or a bare scalar cannot be one.', help='Wrap the content in top-level keys, or check you meant to compile this file.', level='error'), 'off-panel-speaker': Rule(summary='A line is spoken from off panel by somebody drawn in the panel', description="An off-panel speaker is somebody nobody draws: their balloon's tail ends on the frame, on their side, because there is no mouth in the panel to point at. So they are never in the panel's cast. A line marked `off_panel` whose speaker is in the cast contradicts itself, and so does one speaker both on and off panel in the same panel.", help="Leave the speaker out of this panel's cast, or drop off_panel.", level='error'), 'ordering-cycle': Rule(summary='Horizontal ordering contains a cycle', description="`left_of` and `right_of` are resolved into a linear order before the solver runs, because Cassowary is a linear solver and cannot express the disjunction 'A left of B or B left of A'. A cycle has no linear order and so no solution.", help='Remove one of the relations in the cycle; the message names an actor on it.', level='error'), 'page-layout': Rule(summary='A page cannot lay out what it says', description="`pages:` lays the panels of a scene out in tiers. Each placement must name a panel `panels:` defines, a panel can be on one page once, and the margins and gutters must leave room for every tier and every panel in it. A tier holds `panels:` or `columns:`, and two columns that are both stacks may not stand side by side, because readers go across them rather than down. Two insets in one panel must stay a gutter clear of each other. A slant leans the gutters between a tier's panels, so it needs two panels or more, no columns and no insets, and must leave every panel some width at its top and bottom. A panel bleeds only on a side of its frame that reaches the page's margin. A document with pages needs panels to lay out.", help="Check the panel names in `pages:`, place each panel once, put a panel that spans the tier between two stacks, move or shrink an inset, lean a slant less, bleed only on a side at the page's edge, or shrink the margin and gutters in `page:`.", level='error'), 'panel-count': Rule(summary="A comic script's PAGE heading states a count its panels do not match", description="Dark Horse's script format labels each page with how many panels it has, `PAGE ONE (five panels)`. When the panels under it number something else, a panel heading has often been missed, or written so that it reads as prose -- and nothing else would say so. A note, not an error: the panels that are there still compile.", help='Correct the count, or the panel heading that was not read as one.', level='note'), 'panel-direction': Rule(summary='A panel names a reading direction of its own', description="`direction` says which way the whole comic is read -- `ltr` from the top left, `rtl` from the top right, as manga are -- so it is written once for the document: beside `panels:` in a scene, in a comic script's front matter. A page read one way holding a panel read the other has no order a reader could follow, so a panel under `panels:` that writes `direction`, even the document's own, and a script's `@direction:`, are refused.", help='Delete it from the panel, and write `direction` once for the whole document.', level='error'), 'panel-geometry': Rule(summary='The panel has no usable area', description='Panel dimensions must be positive, and the margins must leave something between them. A panel with no interior has nothing to compose in.', help='Give the panel a positive size, and a margin smaller than half its shorter side.', level='error'), 'puppet-file': Rule(summary='A puppet file a cast member names cannot be read', description="A cast member's `reference` that ends in `.puppet.yaml` names a puppet file, read relative to the folder the document is in, as a font or a picture is. It must be a relative path written with `/`, the file must be there, and it must be a puppet: YAML that declares its landmarks, joints, parts, anchors and face, each joint it names declared. A document compiled from text with no file behind it has no folder, and so can name no puppet file unless the file is sent with it. A fault inside the file is reported in it, at the key that is wrong, when the document was checked as a file.", help="Check the path against the document's folder, write it relative to that folder, or fix the puppet where the finding points and check it against `scenet schema --puppet`. Writing one is walked through at https://creatoan.github.io/scenet/howto/add_your_own_character.html.", level='error'), 'reflexive-relation': Rule(summary='A relation relates an actor to itself', description="No predicate in the language means anything reflexively, so an actor placed left of itself is always a typo for a second actor's id.", help='Name a different actor as the object of the relation.', level='error'), 'sfx-placement': Rule(summary='A sound effect has no legal position', description='A sound effect may cover a figure, and balloons may cover it, but it may never cover a face, leave the panel, lie under an inset or overlap another sound effect. Every candidate position -- around its source, around the zone it prefers, and the middle of every zone -- did one of those.', help='Make it smaller or shorter, drop its rotation or arc, or give the panel more room.', level='error'), 'syntax': Rule(summary='The document is not valid YAML', description="The file could not be parsed at all, so nothing further could be checked. Usually an unclosed bracket or quote, or a line indented inconsistently with the ones around it -- and a line that lines up with no line above it is said to be, with how far in the line it likely goes with is. A comic script's front matter is YAML too, and is read the same way.", help='Fix the reported position; YAML errors cascade, so re-check after each fix.', level='error'), 'unbalanced-emphasis': Rule(summary='Emphasis opened with an underscore is never closed', description='A word written between underscores in dialogue or a caption is stressed, and lettered in bold italic. An underscore that opens a span -- nothing alphanumeric before it, something other than a space after it -- needs one that closes it. Without one the compiler would have to guess where the stress ends, and setting the rest of the line in bold italic is a confident wrong answer.', help='Add the closing `_` after the last stressed word, or write `\\_` for an underscore that is not emphasis.', level='error'), 'unknown-actor': Rule(summary='Reference to an actor that is not in the cast', description='Every actor id named in `staging` or `script` must exist in `cast`. This is the check no JSON Schema can perform -- the value is a perfectly good string, it just does not resolve -- and it is among the most common faults in generated documents.', help='Correct the id, or add the actor to `cast`. The message lists the cast.', level='error'), 'unknown-expression': Rule(summary='Reference to an expression the character does not have', description="A cast member's `expression` names one its puppet does not declare. The counterpart of `unknown-pose`: an expression is selected by name exactly as a pose is.", help="Check the name against the puppet's declared expressions.", level='error'), 'unknown-figure': Rule(summary="A figure the panel's picture does not draw", description="A cast member's `figure` names a figure in the artwork contract of the panel's picture. A panel with no picture has nobody for a figure to be. A figure its picture does not declare is simply not in that panel, as a member written `(OP)` is not; a line spoken by it there, or a sound made by it, is reported, with the figures the picture does draw.", help="Check the name against the contract's `figures`, name the picture with `setting.image`, or say the line from off panel, leaving the member out of this panel's cast.", level='error'), 'unknown-key': Rule(summary='Unknown key', description='Validation is strict everywhere: unknown keys are rejected rather than ignored. A misspelled key that was silently dropped would produce a panel that is subtly wrong with no indication of why, which for a language meant to be precise is the worst possible failure.', help='Check the spelling against every key there is: https://creatoan.github.io/scenet/reference/language/keys.html.', level='error'), 'unknown-place': Rule(summary='Reference to a place the library does not have', description='`setting.place` names a preset that does not exist. The counterpart of `unknown-pose`: the key is a real field and the value is a perfectly good string, it just does not resolve to a place the compiler can expand.', help='Check the name against the list of places: https://creatoan.github.io/scenet/reference/language/setting.html#settingplace.', level='error'), 'unknown-pose': Rule(summary='Reference to a pose the character does not have', description="A cast member's `pose` names one its puppet does not declare. The key is spelled correctly -- `pose` is a real field -- but the value does not resolve to anything the referenced character can do.", help="Check the name against the puppet's declared poses.", level='error'), 'unknown-puppet': Rule(summary='Reference to a character the library does not contain', description="A cast member's `reference` names a puppet that is not installed.", help='Check the name against the shipped library, or name a puppet of your own by its file, relative to the document: `reference: puppets/name.puppet.yaml`.', level='error'), 'word-limit': Rule(summary='A balloon, caption or panel holds more words than a letterer fits well', description="Dark Horse's script format asks for 'approximately 25 words per balloon, and about 50 words per panel, max'. It is a house limit, not a contradiction: the panel still compiles, so this is a note, and `scenet check` passes. Words are counted as they are lettered: anything between spaces that holds a letter or a digit, so `--` and an ellipsis are not words, and emphasis markers add none. A panel counts its balloons and captions; a sound effect is not counted.", help='Split the balloon in two, or carry the rest of the words to the next panel.', level='note')}#

Every rule Scenet can report, keyed by its bare identifier.

These identifiers are stable across releases. A ruleId that changes silently closes every alert that referenced the old one and opens a duplicate under the new one, so renaming one is a breaking change even though nothing stops compiling.

class scenet.diagnostics.Diagnostic[source]#

Bases: object

One finding: what is wrong, which rule it breaks, and where.

rule#

Key into RULES.

Type:

str

message#

The same text the prose diagnostic shows, so the two renderings of a finding cannot drift apart.

Type:

str

path#

Location within the document, in pydantic’s loc form. Structural rather than positional, which is what lets a fingerprint survive an edit above it.

Type:

tuple[str | int, ...]

source#

File the finding is in, or None for a string compiled in memory.

Type:

Path | None

region#

Where in the text it is, if that could be determined.

Type:

Region | None

property level: Literal['error', 'note']#

Its rule’s level: a property, so a finding cannot disagree with its rule.

fingerprint(*, root=None)[source]#

A stable identity for this finding, for partialFingerprints.

Deliberately not derived from the line number. A fingerprint that moves when a comment is added at the top of the file turns one long-standing alert into a new alert on every edit, which is precisely what partialFingerprints exists to prevent. The path is structural, so it survives the finding moving down the file but still distinguishes the same fault in two different places.

The file enters as the uri the result reports, not as the path was typed: an editor passes absolute paths and CI relative ones, and one file under one uri has to be one alert.

Parameters:

root (Path | None) – Directory the reported uri is relative to, as given to to_sarif.

Return type:

str

Returns:

A hex digest, stable across runs, platforms and releases.

__init__(rule, message, path=(), source=None, region=None)#
class scenet.diagnostics.Position[source]#

Bases: object

A one-based line and column, as SARIF and every editor count them.

line#

One-based line number.

Type:

int

column#

One-based column number.

Type:

int

__init__(line, column)#
class scenet.diagnostics.Region[source]#

Bases: object

A span of source, from start up to end.

start#

Where the value begins.

Type:

Position

end#

Where it ends. SARIF treats the end column as exclusive, which is also how PyYAML’s end marks behave, so the two agree without adjustment.

Type:

Position

__init__(start, end)#
class scenet.diagnostics.Rule[source]#

Bases: object

One thing a document can be wrong about.

GitHub requires id, shortDescription, fullDescription and help on every rule, and rejects empty strings for them, so all four are mandatory here too.

summary#

One line, shown as the alert title.

Type:

str

description#

What the rule checks and why it exists.

Type:

str

help#

What to do about it.

Type:

str

level#

error for a contradiction, which the compiler cannot build past; note for a house limit, which a letterer works to and a document can exceed and still compile. Only an error makes scenet check fail.

Type:

Literal['error', 'note']

__init__(summary, description, help, level='error')#
scenet.diagnostics.diagnose_file(path, *, library=None, deep=False)[source]#

Check a document on disk, choosing the frontend by extension.

Parameters:
  • path (Path) – The file to check.

  • library (PuppetLibrary | None) – Puppet library to resolve cast references, poses and expressions against. Defaults to the two shipped puppets.

  • deep (bool) – Also run the full compiler on any panel that passes every cheap check. See diagnose_source.

Return type:

list[Diagnostic]

Returns:

Findings in source order, empty if the document is valid.

Raises:

OSError – The file cannot be read. Not reported as a finding, because a file that cannot be opened is a problem with the invocation rather than with a panel.

scenet.diagnostics.diagnose_source(text, *, source=None, base=None, library=None, deep=False)[source]#

Check a document and report everything wrong with it, without raising.

Runs the same validation the compiler does. Where the compiler raises on the first fault, this collects: pydantic reports every field error at once, so a document with four mistakes yields four findings rather than one and three more compilations.

Beyond IR validation, every cast member’s reference, pose and expression is resolved against a puppet library – the IR alone cannot tell pointing from smirking, so without this a document with a nonsense pose reports clean here and then fails build with no rule and no location. The library is read once per call.

Parameters:
  • text (str) – The document source, in the YAML surface syntax.

  • source (Path | None) – Path it came from, used for the reported file and the fingerprint, and the folder the font files it declares are read from.

  • base (Path | Mapping[str, bytes] | None) – That folder, when it is not the one source is in, or there is no source.

  • library (PuppetLibrary | None) – Puppet library to resolve cast references, poses and expressions against. Defaults to the two shipped puppets, exactly as build does.

  • deep (bool) – Also run the full compiler on any panel that passes every cheap check, to additionally catch layout and balloon-placement – at the cost of a real compile, including font metrics. Off by default so check stays the cheap pass it is documented as.

Return type:

list[Diagnostic]

Returns:

Findings in source order. Empty means the document is valid.

Example

>>> from scenet.diagnostics import diagnose_source
>>> found = diagnose_source("panel: {size: [0, 10]}")
>>> found[0].rule
'panel-geometry'
scenet.diagnostics.help_uri(rule)[source]#

Where a rule or a compile note is explained: its entry in the diagnostics reference.

The entry says why it happens and how to fix it, and shows a document that gives it beside the same document fixed. SARIF carries it as each rule’s helpUri.

Parameters:

rule (str) – A rule’s bare id, as RULES keys it, or a compile note’s name.

Return type:

str

Returns:

The entry’s address on the published site, which serves the latest release.

Example

>>> from scenet.diagnostics import help_uri
>>> help_uri("unknown-key")
'https://creatoan.github.io/scenet/reference/diagnostics.html#unknown-key'
scenet.diagnostics.to_sarif(found, *, root=None)[source]#

Build a SARIF 2.1.0 document from a list of findings.

Only the rules actually referenced are emitted. The catalogue is small enough that emitting all of it would be harmless, but a consumer showing “14 rules, 1 result” invites the reader to wonder what the other thirteen did.

Parameters:
  • found (list[Diagnostic]) – The findings, in the order they should appear.

  • root (Path | None) – Directory to report paths relative to, usually the working directory.

Return type:

dict[str, Any]

Returns:

A JSON-serialisable SARIF document. A clean run still produces a full document with an empty results list – a consumer needs the run to know the tool passed, or a clean check is indistinguishable from a check that never ran.