blob: b1f83aa321bab2400e8f9e0b4b2eca99b7856604 [file]
#!/usr/bin/env python3
# ***************************************************************************************************************************
# * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file *
# * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file *
# * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance *
# * with the License. You may obtain a copy of the License at *
# * *
# * http://www.apache.org/licenses/LICENSE-2.0 *
# * *
# * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an *
# * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the *
# * specific language governing permissions and limitations under the License. *
# ***************************************************************************************************************************
"""
Check every ```lang guide=FILE#REGION fence in the docs pages against that region of the juneau-examples-guides module,
and require a pointer on every non-shell fence of a guide page.
Full docs: check-guide-snippets.md
"""
import argparse
import difflib
import re
import sys
import textwrap
from pathlib import Path
from code_fences import iter_fences, page_files
from juneau_root import find_juneau_root
MODULE = Path('juneau-examples', 'juneau-examples-guides')
SEARCH_ROOTS = (Path('src', 'test', 'java'), Path('src', 'test', 'resources'))
GUIDES_DIR = 'pages/guides/'
LANDING = 'pages/guides/00.Guides.md'
UNCHECKED_LANGS = {'bash', 'sh', 'shell', 'console', 'text'}
POINTER_RE = re.compile(r'^guide=([A-Za-z0-9_./-]+)#([A-Za-z0-9_-]+)$')
MARKER_RE = re.compile(r'^\s*(?://|#|<!--)\s*(region|endregion)(?:\s+([A-Za-z0-9_-]+))?\s*(?:-->)?\s*$')
DIFF_LINES = 12
def normalize(text):
"""CRLF to LF, tabs to 4-column stops, trailing whitespace stripped, common indent removed, outer blank lines dropped."""
lines = [line.expandtabs(4).rstrip() for line in text.replace('\r\n', '\n').split('\n')]
lines = textwrap.dedent('\n'.join(lines)).split('\n')
while lines and not lines[0]:
lines.pop(0)
while lines and not lines[-1]:
lines.pop()
return '\n'.join(lines)
def parse_regions(path):
"""Return ({name: raw body}, [(line, message)]) for the region markers in one source file."""
regions, errors = {}, []
open_name, open_line, body = None, None, []
lines = path.read_text(encoding='utf-8', errors='replace').replace('\r\n', '\n').split('\n')
for n, line in enumerate(lines, 1):
m = MARKER_RE.match(line)
if not m:
if open_name is not None:
body.append(line)
continue
kind, name = m.groups()
if kind == 'region':
if name is None:
errors.append((n, 'region without a name'))
elif open_name is not None:
errors.append((n, f'nested region `{name}` inside `{open_name}`'))
elif name in regions:
errors.append((n, f'duplicate region `{name}`'))
else:
open_name, open_line, body = name, n, []
elif open_name is None or name != open_name:
errors.append((n, f'endregion mismatch: `endregion{" " + name if name else ""}` '
f'{"closes `" + open_name + "`" if open_name else "has no open region"}'))
else:
regions[name] = '\n'.join(body)
open_name = None
if open_name is not None:
errors.append((open_line, f'region unterminated: `{open_name}`'))
return regions, errors
def resolve_source(module_dir, file):
"""Return (path, None) for a guide= FILE, or (None, error message).
A bare basename must match exactly one file under the search roots; a relative path is tried under each root.
"""
if '/' in file:
hits = [module_dir / root / file for root in SEARCH_ROOTS if (module_dir / root / file).is_file()]
else:
hits = [p for root in SEARCH_ROOTS for p in sorted((module_dir / root).rglob(file)) if p.is_file()]
if not hits:
return None, f'guide source not found: `{file}`'
if len(hits) > 1:
names = ', '.join(str(p.relative_to(module_dir)) for p in hits)
return None, f'ambiguous guide source `{file}`: {names}'
return hits[0], None
def all_region_names(module_dir):
"""Every (relative path, region name) defined in the module's search roots."""
found = set()
for root in SEARCH_ROOTS:
for path in sorted((module_dir / root).rglob('*')):
if path.is_file():
rel = str(path.relative_to(module_dir))
found.update((rel, name) for name in parse_regions(path)[0])
return found
def check(docs_root, module_dir):
"""Return (failures, checked, unreferenced): failures is [(page, line, message, diff lines)]."""
failures, checked, referenced = [], 0, set()
module_ok = module_dir is not None and module_dir.is_dir()
for page in page_files(docs_root):
rel = page.relative_to(docs_root).as_posix()
on_guide_page = rel.startswith(GUIDES_DIR) and rel != LANDING
for start, info, body in iter_fences(page.read_text(encoding='utf-8')):
words = info.split()
lang = words[0] if words else ''
pointers = [w for w in words[1:] if w.startswith('guide=')]
if not pointers:
if on_guide_page and lang not in UNCHECKED_LANGS:
failures.append((rel, start, 'guide fence without pointer', []))
continue
checked += 1
if len(pointers) > 1:
failures.append((rel, start, f'more than one guide= pointer: {" ".join(pointers)}', []))
continue
m = POINTER_RE.match(pointers[0])
if not m:
failures.append((rel, start, f'malformed guide= pointer `{pointers[0]}` (want guide=FILE#REGION)', []))
continue
file, region = m.groups()
if not module_ok:
failures.append((rel, start, f'guide module not found: {module_dir}', []))
continue
source, error = resolve_source(module_dir, file)
if error:
failures.append((rel, start, error, []))
continue
source_rel = str(source.relative_to(module_dir))
referenced.add((source_rel, region))
regions, errors = parse_regions(source)
if errors:
for line, message in errors:
failures.append((rel, start, f'{source_rel}:{line}: {message}', []))
continue
if region not in regions:
failures.append((rel, start, f'region not found: `{file}#{region}`', []))
continue
want, got = normalize(regions[region]), normalize(body)
if want != got:
diff = list(difflib.unified_diff(want.split('\n'), got.split('\n'), f'{file}#{region}', rel, lineterm=''))
failures.append((rel, start, f'guide fence does not match {file}#{region}', diff[:DIFF_LINES]))
unreferenced = len(all_region_names(module_dir) - referenced) if module_ok else 0
return failures, checked, unreferenced
def parse_args(argv=None):
parser = argparse.ArgumentParser(description='Check guide= fences in pages/ against the juneau-examples-guides module.')
parser.add_argument('--juneau-root', type=Path, default=None,
help='Juneau checkout (default: $JUNEAU_ROOT, then ../master, then ../juneau)')
parser.add_argument('--docs-root', type=Path, default=Path(__file__).resolve().parent.parent,
help='docs checkout to scan (default: parent of scripts/)')
return parser.parse_args(argv)
def main(argv=None):
args = parse_args(argv)
docs_root = args.docs_root.resolve()
juneau_root = find_juneau_root(docs_root, args.juneau_root, allow_missing=True)
failures, checked, unreferenced = check(docs_root, juneau_root / MODULE)
for rel, line, message, diff in failures:
print(f'{rel}:{line}: {message}')
for d in diff:
print(f' {d}')
failing = len({(rel, line) for rel, line, _message, _diff in failures})
print(f'Guide fences checked: {checked}; failing: {failing}; regions unreferenced: {unreferenced}')
return 1 if failures else 0
if __name__ == "__main__":
sys.exit(main())