spec_checks library

The TomSpecs process checks: what a project runs on its specification at a gate, as library functions over the document's text, with the project's own data passed in (read from <spec-root>/checks/).

A separate library from tom_som_dart_runtime.dart, which a document reader needs without these checks: import both where both are used. tom_specs_clitool's spec_checks command is the CLI over them, and the VS Code extension's tools call that command.

Classes

Access
The authorization requirement of an operation or screen.
AnswerImporter
Plans the import of a markdown rendition's answers into a Blueprint YAML.
CoverageEntry
The result for one id.
CoverageExclusion
A recorded exclusion of the exclusion list.
CoverageReport
The measurement: per row, the model sections, the filled ones, and the classes of the empty ones.
CrossCheckReport
The check's result: findings per check, and the two informational lists.
FeatureRegisterFinding
One broken rule, with the id it concerns.
FeatureRegisterReport
The figures the check found, for the summary line.
ImportedAnswer
One answer taken from the markdown.
ImportedValue
A narrative value replaced as a whole (only with allowOtherEdits).
ImportPlan
The outcome of planning an import.
IndexRow
One row of the index.
MarksInPlaceResult
The outcome of acceptMarksInPlace.
Operation
A server operation of the operation registry (INDM > SVOPR).
ProjectIdea
What the parse of the Project Idea found.
ProjectIdeaCoverageReport
The measurement.
ProjectIdeaItem
One id of the Project Idea.
QuestionBlock
A question block found in the Blueprint.
QuestionRegisterConfig
A project's conventions for its question index (<spec-root>/checks/question_register.yaml).
QuestionRegisterGroup
One count column of the status table: the ids of prefix numbered from from to to (each bound optional).
QuestionRegisterStatus
One status of the index: its key (the status's first word), the label the index and the table write, and whether a question in it still waiting for an answer keeps its block in the Blueprint.
RegisterReport
The check's result: the findings, the figures and the rewritten index.
RequiredFieldsReport
The check's result: how many forms it read and what they lack.
RoleModel
The role model of a project's <spec-root>/checks/authorization_cross_check.yaml.
SbpValidation
The outcome of tiers 2 and 3 for one decoded document.
Screen
A screen of the screen inventory (XID > XCS > SCRDZ > SCRINV).
SpecRootDefinition
What a document of one root is checked against: the model, the root's metadata tree and type, and its DocSpecs schema. A generated facade supplies them (tom_som_dart_v0: somSpecModel, d00SolutionBlueprintMetaTree, somDocSpecsSchema('solution-blueprint')), so the checks themselves need no facade.
Step
A use-case step (main success scenario or extension) that names a server operation.
UnfilledSection
One empty section of the Blueprint, as the TSV lists it.
UseCase
A use case of the use-case catalogue (TOMC > PSAAI > INCA).
ValueEdit
A located value and the text it is to hold.
ValueLocation
Where one content value sits in the YAML text.

Enums

CoverageClass
The classes an id can end in, in the order they are tried.
ValueRole
What a located content value is, as far as answer import cares.

Functions

acceptMarksInPlace(String yamlText, SomMetaTree tree, {String? under}) → MarksInPlaceResult
Accepts the inline change marks of yamlText (decoded against tree) in place, only inside the section under when given (/-separated section ids); see the file comment.
checkFeatureRegister(String yamlText) → FeatureRegisterReport
Checks the feature register of the Blueprint in yamlText.
checkQuestionRegister(String blueprintYaml, String clarifications, {QuestionRegisterConfig config = QuestionRegisterConfig.defaults}) → RegisterReport
Checks clarifications (the index file's text) against the question blocks of blueprintYaml, by the project's config (default: QuestionRegisterConfig.defaults).
checkRequiredFields(String blueprintYaml, String metaJson, {String rootClass = 'D00SolutionBlueprint'}) → RequiredFieldsReport
Checks blueprintYaml against the model classes of metaJson, starting at the root class rootClass.
citations(String text) → Set<String>
The ids a text cites, ranges expanded; whole areas as C18.
crossCheckAuthorization(String yamlText, String configYaml) → CrossCheckReport
Runs the six checks over the Blueprint in yamlText with the role model in configYaml.
locateValues(String yamlText, SomMetaTree tree) → Map<String, ValueLocation>
Walks a v2 document's YAML text and returns every content value's location, keyed by document path.
measureCoverage({required String sampleYaml, required String metaJson, required String blueprintYaml, required String rowsYaml, required String reasonsYaml, String? oldBlueprintYaml}) → CoverageReport
Measures blueprintYaml against the model sample sampleYaml and the model metadata metaJson, with the row table rowsYaml and the reason rules reasonsYaml; oldBlueprintYaml, when given, fills the "old" columns.
measureProjectIdeaCoverage(ProjectIdea idea, Map<String, String> sources, {List<CoverageExclusion> exclusions = const []}) → ProjectIdeaCoverageReport
Measures the coverage of idea by the requirements sources.
parseExclusions(String yamlText) → List<CoverageExclusion>
Reads the exclusion list (exclusions: [{id, reason, record}]).
parseProjectIdea(String md) → ProjectIdea
Reads the ids of the Project Idea Markdown in md.
requirementSources(String yamlText) → Map<String, String>
The requirements of the Blueprint in yamlText, each with the text of its source and rationale values.
rewriteValues(String yamlText, List<ValueEdit> edits) → String
yamlText with every edit's block scalar body replaced.
withAnswer(String text, String questionId, String answer, {String? at}) → String
text with the answer of question questionId set to answer ('' clears it), its label carrying the change time at (SOM §11.9.10) or, with none, written untimed as **Answer:** — an import writes what its source held, and a time it would add would be its own, not the answer's.

Exceptions / Errors

ImportVerificationException
Thrown when the rewritten YAML does not decode to the planned document.
MarksSectionNotFound
An --under section path that names no section, as acceptMarksInPlace reports it.
SbpRenderException
A decoded document holds a value the DocSpecs markdown format cannot represent (for example a content with an unterminated code fence), so no rendition can be written.
YamlRewriteException
Thrown when a value cannot be rewritten in place.