lore/.vale.ini at main · anorika77/lore · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
# Lore docs Vale config. The Lore style incorporates rules derived from
# the Microsoft Writing Style Guide alongside project-specific rules (banned
# phrases, Git/Perforce vocabulary, MkDocs-admonition regression check,
# others). Two documented divergences from the style guide are disabled below.
#
# See docs/developing/doc-standards/tools/README.md for usage. Each
# divergence is justified inline in canon/language.md or canon/format.md —
# do not re-enable without updating the relevant callout and the review checklist.

StylesPath = docs/developing/doc-standards/tools/vale/styles
MinAlertLevel = warning
Vocab = Lore

# Vale lints prose only. Code spans, code blocks, and YAML frontmatter
# are not prose and must not be linted.
IgnoredScopes = code, tt
SkippedScopes = script, style, pre, code, frontmatter

[*.md]
BasedOnStyles = Vale, Lore

# Lore docs use a space before and after em/en dashes.
Lore.Dashes = NO

# Lore allows project-voice "we" / "our" / "us" — what the project
# decided, chose, recommends, provides, or did. Instructional "we" is
# still wrong, but that subset is reviewer-enforced rather than Vale-
# enforced.
# (canon/language.md § Pronouns.)
Lore.We = NO

# Lore replaces Vale's default spell-checker with `Lore.Spelling`, which
# adds regex filters for technical-token patterns (camelCase, acronyms,
# CLI flags, file extensions, version strings, …) on top of the default
# American English Hunspell dictionary. The filtered patterns are common
# in technical writing and produce noise under the bare `Vale.Spelling`
# rule. See `tools/vale/styles/Lore/Spelling.yml`. Project jargon (lede,
# ADRs, …) lives in the project vocabulary at
# `tools/vale/styles/config/vocabularies/Lore/accept.txt`.
Vale.Spelling = NO

# --- Per-file rule exemptions for self-documenting canon --------------------
#
# Some canon files document rules whose "wrong" examples must be inline.
# Globs match the file's basename or full path; rules below disable only
# when the source contains the bad-example forms by design.

# canon/doc-types.md and writing-a-doc.md table the four reader-intent
# Diátaxis prompts ("Walk me through learning X.", "I have a goal …").
# The first-person pronouns are voice — what readers ask, not what we
# write. They appear in tabular reference and worked-example headings.
[**/doc-types.md]
Lore.FirstPerson = NO
Lore.HeadingAcronyms = NO

[**/writing-a-doc.md]
Lore.FirstPerson = NO

# canon/language.md documents the Lore.* prose rules. The "Wrong" column
# in each rule's example table contains the very forms the rule bans.
# Same for the Lore-vocabulary table, which compares Lore primitives to
# Git submodule and P4 stream by name.
[**/language.md]
Lore.PermissionVerbs = NO
Lore.ProductNaming = NO
Lore.GitIsmFlagged = NO
Lore.PerforceIsmFlagged = NO

# docs/glossary.md defines the Lore vocabulary, including the Layer / Link
# entries that compare Lore primitives to Git submodules — same intentional
# Git-ism use as in language.md. Lore.GeneralURL fires on the Clone
# entry, where "URL" is the technical term we mean.
[**/glossary.md]
Lore.GitIsmFlagged = NO
Lore.GeneralURL = NO
Lore.Adverbs = NO

# ADRs (docs/developing/decisions/) follow the MADR template. Its section
# headings — Context and Problem Statement, Decision Drivers, Considered
# Options, Decision Outcome, Pros and Cons of the Options — are Title Case by
# convention, and ADR option/section headings legitimately carry technical
# proper nouns and identifiers (FastCDC, DynamoDB, server_main(), AWS, CLI, …)
# that the sentence-case and acronym checkers misfire on. Same rationale as the
# doc-types.md exemption above.
[**/decisions/*.md]
Lore.Headings = NO
Lore.HeadingAcronyms = NO

# docs/faq.md is a frequently-asked-questions page whose section headings ARE
# the questions ("How is Lore licensed?", "How do I get started?", "Where is
# Lore already in use at Epic?"). Question headings necessarily carry end
# punctuation, first-person "I", and interrogatives Vale reads as uncontracted
# ("How is" → "How's"); rewording them would change the questions. Body prose
# is hand-checked to use contractions. Same per-file precedent as doc-types.md.
[**/faq.md]
Lore.HeadingPunctuation = NO
Lore.FirstPerson = NO
Lore.Contractions = NO