@hawkeyexl/manni 2.12.1 → 4.0.0

package/schemas/lint/template.json

@@ -0,0 +1,346 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "manni-lint:template:2",
+  "title": "manni lint template file",
+  "description": "A template file: named doctype templates, plus the reusable fragments they point at with `$ref`. Validated after dereferencing, so no `$ref` survives to be seen here. A template is itself a rule: it describes the page, and it takes every rule key plus `title`, `types` and `extends`.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["templates"],
+  "properties": {
+    "$schema": {
+      "description": "URL of this schema, so an editor can offer completion. Read by editors, never by the linter.",
+      "type": "string"
+    },
+    "info": {
+      "description": "Free-form metadata about the file (title, version, author). Never read by the linter; declared so a file that carries it is not rejected.",
+      "type": "object"
+    },
+    "templates": {
+      "description": "The doctype templates this file defines, keyed by name.",
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[A-Za-z][A-Za-z0-9-_]*$": { "$ref": "#/definitions/template" }
+      }
+    },
+    "components": {
+      "description": "Reusable fragments, targeted by `$ref` from elsewhere in the file. Left unconstrained: a fragment is validated where it is inlined, not where it is declared.",
+      "type": "object"
+    }
+  },
+  "definitions": {
+    "min": {
+      "description": "Fewest occurrences. Absent means one. Deliberately carries no JSON Schema `default`, and neither does any other key in this file: Ajv's `useDefaults` would write one in at load time, and a written-in value is indistinguishable from a value the author typed, so it wins the `extends` merge against the parent's real value. The code reads `undefined` instead.",
+      "type": "integer",
+      "minimum": 0
+    },
+    "max": {
+      "description": "Most occurrences. Absent is unbounded, so write `max: 1` for exactly once and `max: 0` to forbid. Must be at least `min` where both are written; the loader checks that, because JSON Schema cannot compare two siblings.",
+      "type": "integer",
+      "minimum": 0
+    },
+    "id": {
+      "description": "Handle for this rule, unique among its siblings. It appears in messages, and `extends` targets it to replace one inherited rule in place.",
+      "type": "string",
+      "pattern": "^[A-Za-z][A-Za-z0-9-_]*$"
+    },
+    "description": {
+      "description": "Prose description of what the rule is for. Never checked.",
+      "type": "string"
+    },
+    "heading": {
+      "description": "The heading of the section this rule describes. Absent means any heading, or none. A string is exact text, a list is one-of, `{ pattern }` is an unanchored regular expression, and `false` means the section has no heading of its own.",
+      "oneOf": [
+        { "type": "string", "minLength": 1 },
+        {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["pattern"],
+          "properties": {
+            "pattern": { "type": "string", "minLength": 1 }
+          }
+        },
+        { "const": false }
+      ]
+    },
+    "attributes": {
+      "description": "Literal attributes the node must carry. A string is the required value; `true` requires the attribute to be present, and `false` requires it to be absent.",
+      "type": "object",
+      "additionalProperties": {
+        "oneOf": [{ "type": "string" }, { "type": "boolean" }]
+      }
+    },
+    "oneOfSequenceOrContains": {
+      "description": "A rule says what it holds in order (`sequence`) or in any order (`contains`), never both.",
+      "type": "object",
+      "not": { "required": ["sequence", "contains"] }
+    },
+    "noHeadingOnRepeat": {
+      "description": "`repeat` groups sibling rules into one repeated unit, so the group has no heading of its own. Put the heading on the first rule inside it.",
+      "type": "object",
+      "not": { "required": ["heading", "repeat"] }
+    },
+    "noInstructions": {
+      "description": "`instructions` was the language-model hook of doc-structure-lint. manni lint is deterministic and has no model, so a template carrying it is rejected outright rather than silently ignored; the loader turns this into a migration message pointing at manni docevals.",
+      "type": "object",
+      "not": { "required": ["instructions"] }
+    },
+    "template": {
+      "description": "One doctype template. A template is a rule describing the page itself, so it takes every rule key, plus `title`, `types` and `extends`.",
+      "type": "object",
+      "additionalProperties": false,
+      "allOf": [
+        { "$ref": "#/definitions/noInstructions" },
+        { "$ref": "#/definitions/oneOfSequenceOrContains" },
+        { "$ref": "#/definitions/noHeadingOnRepeat" }
+      ],
+      "properties": {
+        "title": {
+          "description": "Human-readable name for the template, shown by `manni lint templates`.",
+          "type": "string"
+        },
+        "types": {
+          "description": "Doctypes this template serves, matched against a page's `type` frontmatter.",
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "extends": {
+          "description": "Template reference (built-in id, path, or URL, optionally with a `#name` fragment) whose rules this template inherits.",
+          "type": "string",
+          "minLength": 1
+        },
+        "id": { "$ref": "#/definitions/id" },
+        "description": { "$ref": "#/definitions/description" },
+        "heading": { "$ref": "#/definitions/heading" },
+        "repeat": { "$ref": "#/definitions/repeat" },
+        "min": {
+          "description": "Refused on a template: a page is one page. Declared here only so the loader can say that in a sentence, rather than leaving Ajv to report an unexpected key.",
+          "type": "integer",
+          "minimum": 0
+        },
+        "max": {
+          "description": "Refused on a template, for the same reason as `min`.",
+          "type": "integer",
+          "minimum": 0
+        },
+        "sequence": { "$ref": "#/definitions/sequence" },
+        "contains": { "$ref": "#/definitions/blockRules" },
+        "sections": { "$ref": "#/definitions/rules" }
+      }
+    },
+    "rule": {
+      "description": "One rule. It describes a section of the page, or, with `repeat`, a run of sections matched as one unit.",
+      "type": "object",
+      "additionalProperties": false,
+      "allOf": [
+        { "$ref": "#/definitions/noInstructions" },
+        { "$ref": "#/definitions/oneOfSequenceOrContains" },
+        { "$ref": "#/definitions/noHeadingOnRepeat" }
+      ],
+      "properties": {
+        "id": { "$ref": "#/definitions/id" },
+        "description": { "$ref": "#/definitions/description" },
+        "heading": { "$ref": "#/definitions/heading" },
+        "repeat": { "$ref": "#/definitions/repeat" },
+        "min": { "$ref": "#/definitions/min" },
+        "max": { "$ref": "#/definitions/max" },
+        "sequence": { "$ref": "#/definitions/sequence" },
+        "contains": { "$ref": "#/definitions/blockRules" },
+        "sections": { "$ref": "#/definitions/rules" }
+      }
+    },
+    "rules": {
+      "description": "Rules for the subsections, in document order.",
+      "type": "array",
+      "items": { "$ref": "#/definitions/rule" }
+    },
+    "repeat": {
+      "description": "Rules matched in order as one unit, repeated by this rule's `min` and `max`.",
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/definitions/rule" }
+    },
+    "sequence": {
+      "description": "What the section holds, in order. Each entry is one run of one content kind.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "allOf": [
+          { "$ref": "#/definitions/blockRules" },
+          { "type": "object", "maxProperties": 1 }
+        ]
+      }
+    },
+    "blockRules": {
+      "description": "Block rules, keyed by content kind. The key is plural because it carries a count: the node model says `codeBlock`, a template says `codeBlocks: { min: 1 }`.",
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "paragraphs": { "$ref": "#/definitions/paragraphs" },
+        "codeBlocks": { "$ref": "#/definitions/codeBlocks" },
+        "lists": { "$ref": "#/definitions/lists" },
+        "tables": { "$ref": "#/definitions/tables" },
+        "admonitions": { "$ref": "#/definitions/admonitions" },
+        "images": { "$ref": "#/definitions/images" },
+        "blockquotes": { "$ref": "#/definitions/counted" },
+        "definitionLists": { "$ref": "#/definitions/counted" },
+        "elements": { "$ref": "#/definitions/elements" }
+      }
+    },
+    "counted": {
+      "description": "A block rule that only counts.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "min": { "$ref": "#/definitions/min" },
+        "max": { "$ref": "#/definitions/max" }
+      }
+    },
+    "paragraphs": {
+      "description": "Paragraph requirements.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "min": { "$ref": "#/definitions/min" },
+        "max": { "$ref": "#/definitions/max" },
+        "pattern": {
+          "description": "Unanchored regular expression every paragraph in the run must match.",
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "codeBlocks": {
+      "description": "Code block requirements.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "min": { "$ref": "#/definitions/min" },
+        "max": { "$ref": "#/definitions/max" },
+        "language": {
+          "description": "Language every code block must be tagged with, as the node model spells it. A list is one-of: the block must declare one of them.",
+          "oneOf": [
+            { "type": "string", "minLength": 1 },
+            {
+              "type": "array",
+              "minItems": 1,
+              "items": { "type": "string", "minLength": 1 }
+            }
+          ]
+        },
+        "fenceInfo": {
+          "description": "Info-string tail after the language, where the format carries one.",
+          "type": "string"
+        }
+      }
+    },
+    "lists": {
+      "description": "List requirements.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "min": { "$ref": "#/definitions/min" },
+        "max": { "$ref": "#/definitions/max" },
+        "ordered": {
+          "description": "Whether the list must be ordered. Absent accepts either.",
+          "type": "boolean"
+        },
+        "items": { "$ref": "#/definitions/listItems" }
+      }
+    },
+    "listItems": {
+      "description": "Requirements applied to every item of every list in the run. Recurses arbitrarily deep.",
+      "type": "object",
+      "additionalProperties": false,
+      "allOf": [{ "$ref": "#/definitions/oneOfSequenceOrContains" }],
+      "properties": {
+        "min": { "$ref": "#/definitions/min" },
+        "max": { "$ref": "#/definitions/max" },
+        "sequence": { "$ref": "#/definitions/sequence" },
+        "contains": { "$ref": "#/definitions/blockRules" }
+      }
+    },
+    "tables": {
+      "description": "Table requirements.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "min": { "$ref": "#/definitions/min" },
+        "max": { "$ref": "#/definitions/max" },
+        "columns": {
+          "description": "The header cells, in order.",
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "admonitions": {
+      "description": "Admonition requirements.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "min": { "$ref": "#/definitions/min" },
+        "max": { "$ref": "#/definitions/max" },
+        "variant": {
+          "description": "Which flavor of admonition. The node model's `variant`, not any one format's spelling.",
+          "enum": [
+            "note",
+            "tip",
+            "important",
+            "caution",
+            "warning",
+            "danger"
+          ]
+        }
+      }
+    },
+    "images": {
+      "description": "Image requirements.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "min": { "$ref": "#/definitions/min" },
+        "max": { "$ref": "#/definitions/max" },
+        "url": {
+          "description": "Where the image must point.",
+          "type": "string"
+        },
+        "alt": {
+          "description": "Alternative text the image must carry.",
+          "type": "string"
+        },
+        "attributes": { "$ref": "#/definitions/attributes" }
+      }
+    },
+    "elements": {
+      "description": "Named-wrapper requirements. `sequence` and `contains` here describe what the element holds, which is never the enclosing section's content.",
+      "type": "object",
+      "additionalProperties": false,
+      "allOf": [{ "$ref": "#/definitions/oneOfSequenceOrContains" }],
+      "properties": {
+        "min": { "$ref": "#/definitions/min" },
+        "max": { "$ref": "#/definitions/max" },
+        "tag": {
+          "description": "The element's name, as an author of the format would write it. A list is one-of: an element counts when it carries any of them.",
+          "oneOf": [
+            { "type": "string", "minLength": 1 },
+            {
+              "type": "array",
+              "minItems": 1,
+              "items": { "type": "string", "minLength": 1 }
+            }
+          ]
+        },
+        "attributes": { "$ref": "#/definitions/attributes" },
+        "sequence": { "$ref": "#/definitions/sequence" },
+        "contains": { "$ref": "#/definitions/blockRules" }
+      }
+    }
+  }
+}

package/templates/lint/tgdp/concept.yaml

@@ -0,0 +1,77 @@
+# Concept, derived from The Good Docs Project's `concept/template_concept.md`
+# at release v1.6.0. The upstream Markdown is vendored at
+# `test/lint/fixtures/tgdp/template_concept.md` and linted against this file, so the
+# two cannot drift.
+#
+# Serves Diataxis's "explanation" as well as TGDP's "concept": they are the
+# same shape under two names.
+#
+# Almost every heading in this doctype is optional - upstream marks all but
+# "Use cases" with an `(Optional)` prefix - so this template mostly constrains
+# *which* sections may appear and *in what order*, and says very little about
+# what goes inside them. That is deliberate: a concept page is prose, and a
+# minimum paragraph count per section would fail pages a reader would call
+# correct.
+#
+# The `(\(Optional\) )?` alternative in each pattern is what lets upstream's own
+# file lint clean: it ships the authoring marker in the literal heading text,
+# where a real page writes just the section name.
+#
+# v2: the page's own body - the summary and the definition that follows it,
+# which upstream deliberately leaves without a heading of its own - is the
+# template's own `contains:` rather than a `title` section's. A concept page
+# explains something, and explanations grow sections the published template
+# never named; the trailing `min: 0` rule is what lets those through.
+info:
+  title: Concept (The Good Docs Project)
+  version: "1.6.0"
+  source: https://gitlab.com/tgdp/templates/-/blob/v1.6.0/concept/template_concept.md
+
+templates:
+  concept:
+    types:
+      - concept
+      - explanation
+    description: >-
+      The page title, whatever the author calls the concept. Its body is the
+      summary that introduces the concept and the definition that follows -
+      upstream notes the definition deliberately carries no heading of its
+      own, so it is checked here rather than in a section.
+    contains:
+      paragraphs:
+        min: 1
+    sections:
+      - id: background
+        description: Context, prehistory, or background for the concept.
+        heading:
+          pattern: '^(\(Optional\) )?Background$'
+        min: 0
+        max: 1
+      - id: use-cases
+        description: >-
+          How a reader benefits from the concept. The one section upstream
+          does not mark optional.
+        heading: Use cases
+        max: 1
+      - id: comparison
+        description: >-
+          A comparison of the options or alternatives the concept sits
+          among. Upstream titles it `Comparison of {thing being compared}`,
+          so only the literal prefix is anchored.
+        heading:
+          pattern: '^(\(Optional\) )?Comparison( of .+)?$'
+        min: 0
+        max: 1
+      - id: related-resources
+        description: >-
+          Links out to related documentation. Upstream recommends "Related
+          concepts" or "Additional information" as more descriptive names,
+          so all three are accepted.
+        heading:
+          pattern: '^(\(Optional\) )?(Related resources|Related concepts|Additional information)$'
+        min: 0
+        max: 1
+      # A concept page explains something, and explanations grow sections the
+      # published template never named. The four above are the ones TGDP
+      # names; anything else the author needs is allowed through.
+      - min: 0

package/templates/lint/tgdp/how-to.yaml

@@ -0,0 +1,64 @@
+# Derived from The Good Docs Project "how-to" template, pinned to v1.6.0:
+# https://gitlab.com/tgdp/templates/-/blob/v1.6.0/how-to/template_how-to.md
+#
+# The upstream Markdown is vendored at test/lint/fixtures/tgdp/template_how-to.md and
+# linted against this file, so the two cannot drift. Where they disagree,
+# upstream is right.
+#
+# v2: the template *is* the page (proposal 0061's grammar). Upstream's `# Title`
+# is a placeholder, so what used to be a `title` section wrapping everything is
+# now the template's own `sections:` directly - there is nothing to say about
+# the H1's heading text or its own content.
+info:
+  title: How-to guide (The Good Docs Project)
+  version: "1.6.0"
+  source: https://gitlab.com/tgdp/templates/-/blob/v1.6.0/how-to/template_how-to.md
+
+templates:
+  how-to:
+    types:
+      - how-to
+    sections:
+      - id: overview
+        description: >-
+          What the guide explains, and optionally when and why a reader
+          would want to do it. A how-to that does not say what task it
+          covers is not a how-to, so at least one paragraph is required.
+        heading: Overview
+        max: 1
+        contains:
+          paragraphs:
+            min: 1
+      - id: before-you-start
+        description: >-
+          Prerequisites. Upstream marks this "{This section is optional}",
+          and the authoring guide repeats that, so it is not required.
+          Its shape varies too much to constrain - a lead-in and a bullet
+          list in the template, but prose or grouped categories in the
+          guide's own examples - so no content counts are set.
+        heading: Before you start
+        min: 0
+        max: 1
+      - id: task
+        description: >-
+          The steps. Upstream's heading is the placeholder "{Task name}",
+          so this is a slot; leaving `max` unbounded lets a page carry
+          several task sections, which the guide explicitly contemplates
+          ("you may break down the task into multiple logical sub-tasks").
+          No `lists` floor: a task that delegates its procedure to
+          sub-tasks legitimately holds no ordered list of its own.
+        sections:
+          - id: sub-task
+            description: >-
+              "### {Sub-task}" - another placeholder heading, and upstream
+              says to "include a sub-task only if the task is big and
+              complex", so it is optional and may occur more than once.
+            min: 0
+      - id: see-also
+        description: >-
+          Related reading. Upstream includes it unconditionally and does not
+          mark it optional the way it marks "Before you start", so it is
+          required. Its body is a mix of prose and links, so nothing is
+          counted.
+        heading: See also
+        max: 1

package/templates/lint/tgdp/manifest.json

@@ -0,0 +1,57 @@
+{
+  "$comment": "Built-in doctype templates derived from The Good Docs Project templates, pinned to release v1.6.0 (\"Iron\"): https://gitlab.com/tgdp/templates/-/tree/v1.6.0. Each entry's `file` is a YAML template beside this manifest; `source` is the upstream Markdown it was derived from, vendored under test/lint/fixtures/tgdp/ and linted against the derived template so the two cannot drift. Run `npm run check:tgdp-pin` to see whether upstream has moved past the pin.",
+  "vendor": "tgdp",
+  "upstream": "https://gitlab.com/tgdp/templates",
+  "pin": "v1.6.0",
+  "templates": [
+    {
+      "id": "tgdp:how-to:1.6",
+      "file": "tgdp/how-to.yaml",
+      "title": "How-to guide (The Good Docs Project)",
+      "types": ["how-to"],
+      "source": "how-to/template_how-to.md"
+    },
+    {
+      "id": "tgdp:tutorial:1.6",
+      "file": "tgdp/tutorial.yaml",
+      "title": "Tutorial (The Good Docs Project)",
+      "types": ["tutorial"],
+      "source": "tutorial/template_tutorial.md"
+    },
+    {
+      "id": "tgdp:reference:1.6",
+      "file": "tgdp/reference.yaml",
+      "title": "Reference (The Good Docs Project)",
+      "types": ["reference"],
+      "source": "reference/template_reference.md"
+    },
+    {
+      "id": "tgdp:concept:1.6",
+      "file": "tgdp/concept.yaml",
+      "title": "Concept (The Good Docs Project)",
+      "types": ["concept", "explanation"],
+      "source": "concept/template_concept.md"
+    },
+    {
+      "id": "tgdp:troubleshooting:1.6",
+      "file": "tgdp/troubleshooting.yaml",
+      "title": "Troubleshooting (The Good Docs Project)",
+      "types": ["troubleshooting"],
+      "source": "troubleshooting/template_troubleshooting.md"
+    },
+    {
+      "id": "tgdp:release-notes:1.6",
+      "file": "tgdp/release-notes.yaml",
+      "title": "Release notes (The Good Docs Project)",
+      "types": ["release-notes"],
+      "source": "release-notes/template_release-notes.md"
+    },
+    {
+      "id": "tgdp:readme:1.6",
+      "file": "tgdp/readme.yaml",
+      "title": "README (The Good Docs Project)",
+      "types": ["readme"],
+      "source": "readme/template_readme.md"
+    }
+  ]
+}