@hawkeyexl/manni 3.0.0 → 4.0.0

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"
+    }
+  ]
+}

package/templates/lint/tgdp/readme.yaml

@@ -0,0 +1,163 @@
+info:
+  title: README (The Good Docs Project)
+  vendor: tgdp
+  pin: v1.6.0
+  source: https://gitlab.com/tgdp/templates/-/blob/v1.6.0/readme/template_readme.md
+
+# Derived from The Good Docs Project's README template. Almost every heading
+# upstream interpolates a project name, so this file leans on two devices:
+#
+#   * A heading that is *entirely* a placeholder (`## {Project Name}`) becomes a
+#     slot - a rule with no `heading` key - because there is no literal text to
+#     anchor on.
+#   * A heading that wraps a placeholder in stable words (`### Install {Project
+#     Name}`, `## Instructions for using {Project Name}`) gets a `pattern`
+#     anchored on those words. Patterns keep neighbouring sections tellable
+#     apart, which a run of adjacent slots cannot do.
+#
+# Only the project title is required. Upstream marks the logo and table of
+# contents optional outright, and treats the rest as boilerplate a project
+# customises or deletes; real READMEs routinely name the same content
+# differently or leave it out. So the teeth here are section *order*, the shape
+# of the instructions subsections, and content minimums that bite only once a
+# section is actually present.
+#
+# v2: the template *is* the page, so what used to be a `title` section wrapping
+# everything - itself nested under a v1 root that also carried its own
+# `additionalSections: true` - collapses into one level, the template's own
+# `sections:`. The root's own `additionalSections` governed siblings of the H1,
+# which a single page never has, so v2 has nothing to say in its place; the
+# `title` rule's `additionalSections: true` is what survives, as the trailing
+# `min: 0` rule at the end of this list.
+templates:
+  readme:
+    types:
+      - readme
+    sections:
+      - id: logo-and-badges
+        description: >-
+          `## {Project} logo and badges`. Explicitly optional upstream.
+          Anchored on the words either side of the placeholder rather than
+          left as a slot, so it cannot swallow whatever section happens to
+          come first.
+        min: 0
+        max: 1
+        heading:
+          pattern: "\\b[Ll]ogos?\\b|\\b[Bb]adges?\\b"
+      - id: project-name
+        description: >-
+          `## {Project Name}` - the heading is nothing but a placeholder,
+          so this is a slot. One section, never a run.
+        min: 0
+        max: 1
+        sections:
+          - min: 0
+      - id: table-of-contents
+        description: >-
+          Explicitly optional upstream. A table of contents that holds no
+          list is not one, hence the list minimum.
+        min: 0
+        max: 1
+        heading: Table of contents
+        contains:
+          lists:
+            min: 1
+      - id: project-description
+        description: What the project is and what it lets you do.
+        min: 0
+        max: 1
+        heading: Project description
+        contains:
+          paragraphs:
+            min: 1
+        sections:
+          - min: 0
+      - id: who-this-project-is-for
+        description: The intended audience and their objective.
+        min: 0
+        max: 1
+        heading: Who this project is for
+        contains:
+          paragraphs:
+            min: 1
+      - id: project-dependencies
+        description: >-
+          Prerequisites. No list minimum: upstream's own troubleshooting
+          content shows these sections are as often tables, which the
+          parser does not count as lists.
+        min: 0
+        max: 1
+        heading: Project dependencies
+      - id: instructions-for-use
+        description: >-
+          `## Instructions for using {Project Name}`, anchored on the
+          literal opening words. Its subsections are the install/configure/
+          run/troubleshoot procedure, each of which is itself optional and
+          itself heading-anchored.
+        min: 0
+        max: 1
+        heading:
+          pattern: "^Instructions\\b"
+        sections:
+          - id: install
+            description: "`### Install {Project Name}`."
+            min: 0
+            max: 1
+            heading:
+              pattern: "^Install"
+            sections:
+              - min: 0
+          - id: configure
+            description: "`### Configure {Project Name}`."
+            min: 0
+            max: 1
+            heading:
+              pattern: "^Configur"
+            sections:
+              - min: 0
+          - id: run
+            description: "`### Run {Project Name}`."
+            min: 0
+            max: 1
+            heading:
+              pattern: "^Run(ning)?\\b"
+            sections:
+              - min: 0
+          - id: troubleshoot
+            description: "`### Troubleshoot {Project Name}`."
+            min: 0
+            max: 1
+            heading:
+              pattern: "^Troubleshoot"
+            sections:
+              - min: 0
+          - min: 0
+      - id: contributing-guidelines
+        description: How to contribute, or a link to the contributing guide.
+        min: 0
+        max: 1
+        heading: Contributing guidelines
+        contains:
+          paragraphs:
+            min: 1
+      - id: additional-documentation
+        description: Links to further reading.
+        min: 0
+        max: 1
+        heading: Additional documentation
+      - id: how-to-get-help
+        description: Support resources.
+        min: 0
+        max: 1
+        heading: How to get help
+      - id: terms-of-use
+        description: The licence the project is published under.
+        min: 0
+        max: 1
+        heading: Terms of use
+        contains:
+          paragraphs:
+            min: 1
+      # Tolerate a document that carries more than one top-level heading
+      # beyond the ones named above.
+      - min: 0

package/templates/lint/tgdp/reference.yaml

@@ -0,0 +1,67 @@
+# Reference, derived from The Good Docs Project's `reference/template_reference.md`
+# at release v1.6.0. The upstream Markdown is vendored at
+# `test/lint/fixtures/tgdp/template_reference.md` and linted against this file, so the
+# two cannot drift.
+#
+# v2: upstream ships the H1 as `# Reference template`, but a real reference
+# names its own subject, so there is nothing to say about the page's own
+# heading. No paragraph minimum either: the published template carries only
+# block quotes under the H1, and a reference that opens straight into its
+# first entry section is well formed.
+info:
+  title: Reference (The Good Docs Project)
+  version: "1.6"
+  source: https://gitlab.com/tgdp/templates/-/blob/v1.6.0/reference/template_reference.md
+
+templates:
+  reference:
+    types:
+      - reference
+
+    sections:
+      - id: reference-description
+        description: >-
+          `## {Reference description}` - a placeholder heading, so a slot.
+          Summarizes what the reference covers and how it relates to the
+          rest of the doc set. Required: the guide makes this the section
+          that "concisely summarizes the reference article's content and
+          purpose".
+        max: 1
+
+      - id: structured-entry
+        description: >-
+          `## {Table name or other structured entry}` - a placeholder
+          heading standing for a repeated section, so a slot with an
+          unbounded `max`. Claims every consecutive section up to
+          `commands`. Optional because it and `reference-description` are
+          both unconstrained placeholders: the matcher cannot tell "the
+          description" from "the first entry", so requiring both would
+          mandate two H2s where the doctype only asks that entries exist.
+          The node model can name a table directly (proposal 0065), so this
+          asks for one. Every parser reports tables now, so the rule runs and
+          upstream's own table satisfies it. Against a format that cannot
+          report them the rule is pruned and reported as an
+          `unsupported_content_kind` warning, rather than silently passing or
+          failing a page for a shape that format cannot show.
+        min: 0
+        contains:
+          tables:
+            min: 1
+
+      - id: commands
+        description: >-
+          `## (Optional) Commands`. The guide calls this "this optional
+          section" outright. The pattern accepts the heading with the
+          `(Optional)` marker still attached, as upstream ships it, and
+          with the marker removed, as an author who keeps the section would
+          write it. A section named anything else - "CLI commands",
+          "Command reference" - simply falls to the entry slot above.
+        min: 0
+        max: 1
+        heading:
+          pattern: '^(?:\(Optional\)\s+)?Commands$'
+
+      # Reference pages routinely end with sections the doctype does not
+      # enumerate - "See also", "Related information", "Notes". The upstream
+      # template does not forbid them, so they are not findings.
+      - min: 0

package/templates/lint/tgdp/release-notes.yaml

@@ -0,0 +1,108 @@
+# Release notes, derived from The Good Docs Project's published template at
+# v1.6.0 ("Iron"):
+# https://gitlab.com/tgdp/templates/-/blob/v1.6.0/release-notes/template_release-notes.md
+#
+# Almost everything here is optional, on purpose. A release notes page is a
+# report on one release, and no release has every kind of change in it: a
+# maintenance release with three bug fixes and nothing else is a correct
+# release notes page, and a template that demanded "New features" would be
+# wrong about it. What the doctype genuinely mandates is the title. What this
+# template is *for* is asserting that the sections which do appear carry
+# upstream's names and appear in upstream's order - so `## Bug Fixes`,
+# `## Fixes`, or a "Bug fixes" section placed above "New features" is reported,
+# while a page that simply omits four of the six categories is not.
+#
+# That assertion is why the template itself carries no trailing wildcard rule:
+# an unrecognised H2 has to be reported for the naming check to have any force.
+# Inside a category the opposite holds - upstream prescribes the category
+# headings, not how a category is subdivided - so each one ends with a
+# trailing `min: 0` rule that lets any subsection through.
+#
+# There are no paragraph, list, or code-block minimums anywhere. Upstream marks
+# only the release date as non-optional prose, and a category whose body is a
+# single bullet list, a table, or a paragraph are all ordinary shapes for this
+# doctype; counting blocks would fail correct pages without catching a real
+# structural mistake.
+info:
+  title: Release notes (The Good Docs Project)
+  version: "1.6.0"
+  source: https://gitlab.com/tgdp/templates/-/blob/v1.6.0/release-notes/template_release-notes.md
+
+templates:
+  release-notes:
+    types:
+      - release-notes
+    description: >-
+      The page itself. Upstream titles it
+      `Release notes - {Product name} {Release number}`; only the braced
+      parts are placeholders, so the literal prefix is the one thing this
+      template insists on. Its body carries the release version, the
+      release date, and an optional high-level summary.
+    heading:
+      pattern: '^Release [Nn]otes\b'
+    sections:
+      - id: new-features
+        description: Functionality this release adds. Omitted by a release that adds none.
+        heading: New features
+        min: 0
+        max: 1
+        sections:
+          - min: 0
+
+      - id: new-features-requiring-configuration-updates
+        description: >-
+          New functionality that does not switch itself on. Separated from
+          `New features` upstream because these entries are action items
+          for the reader, not announcements.
+        heading: New features requiring configuration updates
+        min: 0
+        max: 1
+        sections:
+          - min: 0
+
+      - id: improvements
+        description: Changes to functionality that already existed - speed, usability, behaviour.
+        heading: Improvements
+        min: 0
+        max: 1
+        sections:
+          - min: 0
+
+      - id: api-web-service-updates
+        description: Changes to programmatic interfaces, which have a different audience from the rest of the page.
+        heading: API/Web service updates
+        min: 0
+        max: 1
+        sections:
+          - min: 0
+
+      - id: bug-fixes
+        description: Defects resolved in this release.
+        heading: Bug fixes
+        min: 0
+        max: 1
+        sections:
+          - id: known-issues
+            description: >-
+              Defects that are known and *not* resolved. Upstream nests this
+              under `Bug fixes` rather than making it a category of its own,
+              which puts what is still broken next to what was fixed.
+            heading: Known issues
+            min: 0
+            max: 1
+            sections:
+              - min: 0
+          - min: 0
+
+      - id: deprecation-notice
+        description: >-
+          Functionality being retired, with the date it stops being
+          supported and what replaces it. Upstream writes the heading as
+          `Optional: Deprecation notice`, so the pattern accepts the
+          published form as well as the one a real page would use.
+        heading:
+          pattern: '^(Optional: )?Deprecation notice$'
+        min: 0
+        max: 1
+        sections:
+          - min: 0

package/templates/lint/tgdp/troubleshooting.yaml

@@ -0,0 +1,98 @@
+# Troubleshooting, derived from The Good Docs Project's troubleshooting
+# template at release v1.6.0 ("Iron"):
+#
+#   https://gitlab.com/tgdp/templates/-/blob/v1.6.0/troubleshooting/template_troubleshooting.md
+#
+# The upstream file is vendored at test/lint/fixtures/tgdp/template_troubleshooting.md
+# and linted against this template, so the two cannot drift.
+#
+# The doctype is a list of symptoms, each explained by one or more causes and
+# the solution or workaround for each. Upstream numbers every heading -
+# `## Symptom 1`, `### Cause 2 of symptom 1` - but the numbering is
+# illustrative, so the patterns here anchor on the leading word only: a page
+# with one symptom, a page with five, and a page whose headings read
+# `Symptom: disk full` or `Workaround` all pass. An unbounded `max` on an
+# anchored rule claims the whole run of consecutive sections whose headings
+# satisfy it, which is what lets the heading text be checked and repeated at
+# once.
+#
+# v1 could not repeat a *pair* of rules, so it fell back to one rule matching
+# either word ("Cause" or "Solution"), losing the doctype's actual order. v2's
+# `repeat:` groups sibling rules into one repeated unit, which is exactly what
+# the alternation is: each unit is one required Cause followed by one optional
+# Solution or Workaround - optional because upstream's own file has a cause
+# with no heading solution beneath it (the second solution in "Symptom 1" is
+# unheaded prose, not a subsection). The unit itself repeats without limit, so
+# a symptom may carry as many cause/solution pairs as it needs.
+info:
+  title: Troubleshooting (The Good Docs Project)
+  version: "1.6.0"
+  source: https://gitlab.com/tgdp/templates/-/blob/v1.6.0/troubleshooting/template_troubleshooting.md
+
+templates:
+  troubleshooting:
+    types:
+      - troubleshooting
+    description: >-
+      The page itself (H1). Upstream titles it
+      `# Troubleshooting {product name, feature, or task}`, a placeholder,
+      so the text is left free. What the doctype does ask for is underneath
+      it: the one- or two-sentence statement of what the guide covers,
+      which is how a reader decides in seconds whether they are in the
+      right document.
+    contains:
+      paragraphs:
+        min: 1
+    sections:
+      - id: symptom
+        description: >-
+          One thing the reader might be seeing - an error message, a
+          failure, a performance problem. An unbounded `max` claims every
+          consecutive H2 whose title starts with "Symptom". The number
+          upstream attaches (`## Symptom 1`) is not required, so
+          `## Symptom: sync stalls` is equally acceptable.
+        heading:
+          pattern: '^[Ss]ymptoms?\b'
+        sections:
+          - id: cause-or-solution
+            description: >-
+              One cause of the symptom, optionally followed by its solution
+              or workaround - `### Cause 1 of symptom 1`, then
+              `### Solution or workaround to cause 1 of symptom 1`. The
+              solution is optional within the pair because upstream's own
+              file pairs a second cause with no heading solution at all.
+            repeat:
+              - id: cause
+                description: >-
+                  At least one is required: a symptom with no cause is not
+                  a troubleshooting entry. Content is left unconstrained,
+                  because the guide recommends bullet points for symptoms
+                  and numbered steps for solutions, so a section here may
+                  legitimately hold no paragraph at all.
+                heading:
+                  pattern: '^[Cc]auses?\b'
+                max: 1
+              - id: solution
+                heading:
+                  pattern: '^([Ss]olutions?|[Ww]orkarounds?)\b'
+                min: 0
+                max: 1
+          - id: for-more-information
+            description: >-
+              Further reading for this symptom. Optional, and anchored, so
+              the repeating pair above stops at it rather than treating it
+              as one more cause.
+            heading: For more information
+            min: 0
+            max: 1
+      - id: for-more-information
+        description: >-
+          Further reading for the guide as a whole. Upstream writes this
+          heading at H3, inside the last symptom, which reads like a level
+          slip - its text ("other sources ... with your product, task, or
+          feature") is about the product, not about one symptom. Rather
+          than pick a side, the section is allowed, and optional, at both
+          levels.
+        heading: For more information
+        min: 0
+        max: 1