-
Notifications
You must be signed in to change notification settings - Fork 9
Open
Labels
Description
Summary
The frontmatter validation script applies the wrong schema to README.md files in subdirectories, causing false positive warnings.
Root Cause
The Get-SchemaForFile function in scripts/linting/Validate-MarkdownFrontmatter.ps1 has a pattern matching issue:
# Line 270-271: Root file pattern check
if ($rule.pattern -match '\|') {
$patterns = $rule.pattern -split '\|'
if ($fileName -in $patterns) { # ← Matches README.md in ANY locationWhen a file is named README.md, it matches the root pattern README.md|CONTRIBUTING.md|... regardless of which directory it's in.
Impact
Files incorrectly validated with root-community-frontmatter.schema.json:
docs/getting-started/README.md(should usedocs-frontmatter.schema.json)docs/rpi/README.md(should usedocs-frontmatter.schema.json)docs/contributing/README.md(should usedocs-frontmatter.schema.json).github/chatmodes/README.md(should use a github schema).github/prompts/README.md(should use a github schema).devcontainer/README.md(should use a devcontainer schema or base)
Current Warnings
WARNING: JSON Schema validation errors in docs/getting-started/README.md:
WARNING: - Field 'ms.topic' must be one of: overview, concept, reference. Got: tutorial
The tutorial value IS valid in docs-frontmatter.schema.json, but the wrong schema is being applied.
Proposed Fix
Task 1: Fix pattern matching order in schema-mapping.json
Process more specific patterns before generic ones:
{
"mappings": [
{ "pattern": ".github/**/*.md", "schema": "..." },
{ "pattern": "docs/**/*.md", "schema": "docs-frontmatter.schema.json" },
{ "pattern": ".devcontainer/**/*.md", "schema": "..." },
{ "pattern": "README.md|CONTRIBUTING.md|...", "scope": "root-only", "schema": "root-community-frontmatter.schema.json" }
]
}Task 2: Update Get-SchemaForFile logic
- Check directory scope before matching filename patterns
- Process glob patterns (
docs/**/*.md) before pipe-separated filename patterns - Only apply root pattern to files actually in repo root
Task 3: Expand ms.topic enum values
| Schema | Add Values |
|---|---|
root-community-frontmatter.schema.json |
guide, hub-page |
docs-frontmatter.schema.json |
architecture, research |
base-frontmatter.schema.json |
guide, hub-page, architecture |
Related
Discovered during PR #102