@hawkeyexl/manni 2.12.1 → 4.0.0

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

package/templates/lint/tgdp/tutorial.yaml

@@ -0,0 +1,74 @@
+# Tutorial, derived from The Good Docs Project's tutorial template.
+#
+# Upstream (the authority for every heading below):
+#   https://gitlab.com/tgdp/templates/-/blob/v1.6.0/tutorial/template_tutorial.md
+#   https://gitlab.com/tgdp/templates/-/blob/v1.6.0/tutorial/guide_tutorial.md
+#
+# The upstream Markdown is vendored at test/lint/fixtures/tgdp/template_tutorial.md
+# and linted against this file, so the two cannot drift.
+#
+# What is checked here is structure: which sections a tutorial has, and in what
+# order. Content counts are almost entirely absent on purpose - a tutorial's
+# steps may be a numbered list, a run of subsections, or a mix, and a minimum
+# tuned to the sample page would reject real pages that are perfectly good
+# tutorials.
+#
+# v2: upstream's `# Title` is a placeholder, so there is nothing to say about
+# the page's own heading or content - what used to wrap everything in a
+# `title` section is now the template's own `sections:`.
+info:
+  title: Tutorial (The Good Docs Project)
+  version: "1.6.0"
+  vendor: tgdp
+  pin: v1.6.0
+
+templates:
+  tutorial:
+    types:
+      - tutorial
+    sections:
+      - id: overview
+        heading: Overview
+        max: 1
+        description: >-
+          What the reader will be able to do by the end, who the tutorial
+          is for, and the background knowledge it assumes. The guide calls
+          this the section that decides whether a reader starts at all, so
+          it must say something in prose.
+        contains:
+          paragraphs:
+            min: 1
+      - id: background
+        heading: Background
+        min: 0
+        max: 1
+        description: >-
+          Context the reader needs before starting - what the feature is,
+          or how a supplied starter project is laid out. Upstream marks
+          this section optional in the template body ("{This section is
+          optional.}").
+      - id: before-you-start
+        heading: Before you start
+        max: 1
+        description: >-
+          Prerequisites: prior knowledge, software, environments, access.
+          No content minimum - a prerequisites section that is nothing but
+          a bulleted list is idiomatic.
+      - id: task
+        description: >-
+          One task the tutorial walks the reader through. Upstream heads it
+          with a placeholder (`## {Task name}`), so this rule constrains no
+          heading text. Leaving `max` unbounded is what lets a tutorial be a
+          sequence of these: the placeholder stands for however many the
+          page needs.
+      - id: summary
+        heading: Summary
+        max: 1
+        description: >-
+          The skills and knowledge the reader has gained, stated as
+          outcomes rather than as a repeat of the learning objectives.
+      - id: next-steps
+        heading: Next steps
+        max: 1
+        description: >-
+          Links onward - related tutorials, articles, videos.