Quality
25 terms described. A term is a word of the business with its definition, its aliases and the words it relates to.
| Term | aliases | First line | Links |
|---|---|---|---|
| Build log | build.log.json, log | The file build.log.json the build writes next to the site: its summary (sources, files, entities per type, links per method, keyword pages and expressions under the threshold, twin resources, the decisions of the lock applied, findings per severity and per check, the contracts imported) and every finding, sorted by check, source, path, line and message. Its findings array is the same as the one embedded in the model, and its only timestamp is its at field. The log is written before the verdict of build.fail_on, so a failing build still leaves it for inspection. | 67 |
| Check | control, rule of consistency | A pure function that reads the model and returns findings. Checks live in one registry shared by the build and the linter, so both report the same thing on the same repository. Each check has an identifier, a default severity, a description, a remediation and a documentation page, and belongs to a check family. | 139 |
| Check family | family | The grouping of the checks in their documentation: every check page states its family, and the list of the checks is laid out by family, source checks, link checks, identifier and type checks, document checks, vocabulary and filing checks, contract checks and plugin checks. The family says which step of the pipeline raises the finding and which note or file it points at. | 73 |
| Contract checks | contracts family | The check family of the APIs and their contracts: W-CONTRACT-UNREACHABLE, a contract the contract import could not fetch, read or parse; W-OPERATION-AMBIGUOUS, two operation notes claiming one imported operation, or one note matching several; W-API-NOCONSUMER, an API nothing consumes; W-API-CONSUMER-MISMATCH, a declared consumer that never cites the API, or a citing note the API does not list. | 16 |
| Contribution point | contribution, manifest key | One of the ways a plugin adds to the tool, named by a key of its manifest: readers (a reader per file format), converters (a converter), sources (a source of entities such as a contract import), inferenceMethods (a method that produces links), checks (a check with its identifier, severity, remediation and page), projections (a rendering of the model), uiComponents (a bundle a slot loads on demand), themes (a theme with components by slot) and types (a type module per folder, merged into the profile). The data around each contribution is validated by the plugin schema; the functions are called with their input and an injected context, and never read the clock or the network on their own. | 62 |
| Determinism | reproducible build, byte-identical | Two builds of unchanged sources write the same bytes: every list of the model, of the build log, of the fragments and of the site is sorted canonically before it is written, a parallel step sorts its results, nothing random is written and the only timestamp is the at field of the log and of the build block of the model, pinned by SOURCE_DATE_EPOCH as reproducible-builds tooling does. The repository builds its golden corpus twice on every change and compares every file, so that dist/ can be committed and diffed. | 52 |
| Document checks | documents family | The check family of the documents that are not notes: W-CONV-FAILED, an office document the converter could not turn into a PDF; W-CONV-SUSPECT, a converted PDF without extractable text although the document is large; W-DOC-NOMD, a document without a markdown representation, which the to-do page lists; W-DUP-CANDIDATE, two resources that look like twin resources without reaching the merge score. | 22 |
| Excluded file | exclude, excluded file, ignored file, gitignore | A file of a knowledge repository that is never read, never counted and never reported, by the linter and by the build alike: what privacy.exclude of the privacy block names for the whole wiki, what exclude of the repository's own concordance-lint.yaml names for that repository, both as globs relative to its root, and what git ignores, read from every .gitignore of the repository with the rules git applies. A vendored folder, a generated site or a cloned tool thus stay out of the checks and out of the link resolution, so that a link towards an excluded file is a broken link; concordance lint --no-gitignore reads the ignored files anyway, for the rare repository that keeps notes in an ignored folder. Because both sides list the files the same way, the local checks keep their parity file for file. | 33 |
| Finding | constat, diagnostic | The result of a check on an entity, a link or a file: an identifier, a severity, a file and line, a message and a remediation. A content anomaly becomes a finding, never a crash. The build fails only when the configuration says so; the linter fails from the severity it is told to fail on. | 150 |
| Forge report | SARIF log, JUnit report, lint report | The report the linter writes for a forge with --format: a SARIF log that GitHub code scanning shows in the margin of the diff, on the file and line of each finding; a JUnit report that a GitLab merge request lists as failed tests with the message, the remediation and the page of each; or JSON, which also names the scope, the checks that ran and whether the global scope was degraded. Every form carries the same findings as the text output, and --output writes it to a file, the only file the linter ever writes. | 33 |
| Global check | GLOBAL_CHECKS, global scope check | A check the linter computes on one repository against the published model of the whole wiki, without rebuilding it: a markdown link into another source, a frontmatter reference whose relation the profile must allow between the two types, or a title shared with an entity of another type. The lint package lists them as GLOBAL_CHECKS (E-LINK-BROKEN, E-META-REL, I-TERM-HOMONYM, W-LINK-CROSS-SOURCE). The model is fetched once and kept in a local cache for a configurable number of hours; when it cannot be read, the linter says so and falls back to the local checks instead of failing. Each finding names the remote entity and the build timestamp of the model it was compared with. | 29 |
| Golden corpus | reference corpus, fixtures | A fixed corpus in which the tool describes itself, in English and in French, with the model and findings the engine must produce from it. Every story is tested against it; a change in the expected result goes through a reviewed pull request. This glossary and its companion specification repository are the public counterpart: real content about the tool itself. | 62 |
| Identifier and type checks | identifiers and types family | The check family of the reading and typing of a file: E-ENCODING, a file that is not UTF-8; E-FM-INVALID, a frontmatter that does not parse; E-ID-INVALID and E-ID-DUP, an identifier that breaks the pattern or that two files share; E-TYPE-CONFLICT, a frontmatter type contradicting the suffix; E-META-REL, a declared relation the profile forbids between two types; W-TYPE-UNKNOWN, a type the profile does not declare; W-ATTRIBUTE-UNKNOWN, a frontmatter key neither the type nor the common attributes declare. | 19 |
| Link checks | links family | The check family of what a note points at: E-LINK-BROKEN, a markdown link to a file that does not exist in its source; W-LINK-CROSS-SOURCE, a link into another source while inference.cross_source_links is off; W-REF-UNRESOLVED, a frontmatter reference that matches no note, or several by title. The first is a local check, the first two are also computed in the global scope of the linter. | 25 |
| Linter | concordance lint, lint command | The lint command: it reads every markdown file of one knowledge repository but the excluded ones, runs the checks that a repository can be held to alone, and prints one line per finding with the address of its documentation page, then a count. In repo scope it needs no network and writes nothing but the report --output names; in global scope it also reads the published model of the wiki. The linter and the build produce the same findings for the local checks, it fails from the severity --fail-on gives, writes a forge report on request, applies the safe fixes with --fix, and runs the same way as an npm package, a standalone binary, a GitHub action, a GitLab component, the container image or a pre-commit hook. | 70 |
| Local check | LOCAL_CHECKS, local scope check | A check the linter computes on one repository alone, without the network and without the rest of the model: encoding, frontmatter, identifiers and internal links. The lint package lists them as LOCAL_CHECKS. For these checks the linter and the build produce the same findings on the same repository, wording included; a parity test on the golden corpus and on the faulty corpus holds them to it, and the JSON report of the linter repeats the list so that a forge report says what was checked. | 42 |
| Plugin | extension | A package that contributes to the tool through a versioned API: a reader for a file format, a converter, a source of entities such as a contract importer, an inference method, a check, a projection, a user interface component. The core reads markdown and produces JSON; everything that needs a format or a system tool is a plugin. A plugin whose system dependency is missing disables itself with a finding. | 87 |
| Plugin checks | plugins family | The check family of the plugins: W-PLUGIN-DISABLED, a declared plugin whose system tool is not installed, so that it was not registered and the build went on without its contributions; info when the tool is optional and the plugin stays registered. | 17 |
| Preset | batteries included | The package named concordance, which depends on the core and on every official plugin and enables them all. It is what an integrator installs; the core alone is a documented, advanced case. | 13 |
| Release | release tag, published version | One version of the tool, cut by merging the version pull request the pipeline keeps open from the changesets: the merge commit is tagged v<major>.<minor>.<patch>, every published package is packed and attached to a release with the standalone binaries of the linter, the checksums and the licence inventory, and the same tarballs go to npm, the container image to its registry and the action and the component to their mirrors once the maintainer has enabled each publication. Every form of a version names the same commit, so a version pinned in a pipeline, a hook or an image is one registry of checks with one behaviour, and the version of the tool written in the site and the model is that of the release. | 30 |
20 quality of 25 — pagination by twenty. The Links column counts the related pages, which brings the most central quality of the journey to the top.