原始资料 · reports/evidence-documentation/document-checker.txt · 以可阅读文本展示,HTML 与脚本不会在页面中执行。
# 文档审阅工具:检查本地路径/锚点、代码块与示例语法,不访问外网或用户数据库。 from pathlib import Path import ast,hashlib,json,re,subprocess,unicodedata from urllib.parse import unquote root=Path.cwd();evidence=root/'docs/reports/evidence-documentation' files=[root/'README.md',root/'goal.md',*sorted((root/'docs').rglob('*.md'))] def anchor_set(path): found=set();counts={};fenced=False for line in path.read_text().splitlines(): if line.startswith(('```','~~~')):fenced=not fenced;continue if fenced:continue heading=re.match(r'^#{1,6}\s+(.+?)\s*#*$',line) if heading: text=re.sub(r'\[([^]]+)\]\([^)]*\)',r'\1',heading.group(1)).lower() text=''.join(c for c in text if c in '-_ ' or not unicodedata.category(c).startswith(('P','S'))).replace(' ','-') count=counts.get(text,0);counts[text]=count+1 found.add(text+(f'-{count}' if count else '')) return found links=0;fences=0;python_examples=0 for p in files: content=p.read_text();inside=False;marker='';language='';block=[] for i,line in enumerate(content.splitlines(),1): match=re.match(r'^\s*(`{3,}|~{3,})(.*)$',line) if match: if not inside:inside=True;marker=match[1][0];language=match[2].strip();block=[];fences+=1 elif match[1][0]==marker: if p.name=='api-guide.md' and language=='python':ast.parse('\n'.join(block));python_examples+=1 inside=False continue if inside:block.append(line);continue for link in re.finditer(r'\[[^\]]*\]\(([^)\n]+)\)',line): target=link.group(1) if re.match(r'^[a-zA-Z][a-zA-Z0-9+.-]*:',target):continue if target.startswith('<'):target=target[1:target.index('>')] else:target=target.split(' "',1)[0] raw,_,anchor=unquote(target).partition('#') dest=(p.parent/raw).resolve() if raw else p assert dest.exists(),f'{p.relative_to(root)}:{i}: broken link {target}' if anchor and dest.suffix=='.md':assert anchor in anchor_set(dest),f'{p.relative_to(root)}:{i}: broken anchor {target}' links+=1 assert not inside,f'{p}: unclosed code fence' source=[];functions=0 for top in ['backend','cmd','api']: for p in sorted((root/top).rglob('*.go')): lines=p.read_text().splitlines();source.append(p) for i,line in enumerate(lines): if line.startswith('func '): assert i>0 and lines[i-1].lstrip().startswith('//'),f'{p}:{i+1}: missing function documentation' functions+=1 for top in ['frontend/src','frontend/tests','frontend/scripts','scripts','deploy','.github']: source.extend(p for p in (root/top).rglob('*') if p.is_file() and p.suffix in ['.ts','.tsx','.css','.mjs','.py','.sh','.yaml','.yml','.service','.example']) source.extend(root/name for name in ['Dockerfile','Dockerfile.runtime','go.mod','go.sum','frontend/package.json','frontend/package-lock.json','api/openapi.json','frontend/tsconfig.json']) source=sorted(set(source)) for paths,target in [(source,'source-SHA256SUMS'),(files,'documentation-SHA256SUMS')]: (evidence/target).write_text(''.join(hashlib.sha256(p.read_bytes()).hexdigest()+' '+str(p.relative_to(root))+'\n' for p in paths)) for p in (root/'scripts').glob('*.sh'):subprocess.run(['bash','-n',str(p)],check=True) for p in (root/'scripts').glob('*.py'):ast.parse(p.read_text()) unformatted=subprocess.check_output(['gofmt','-l','backend','cmd','api'],text=True);assert not unformatted,unformatted result={'markdown_files':len(files),'local_links_and_anchors_checked':links,'fenced_code_blocks':fences,'python_examples_parsed':python_examples,'go_files':len(list((root/'backend').glob('*.go')))+len(list((root/'cmd').rglob('*.go')))+len(list((root/'api').glob('*.go'))),'go_functions_with_adjacent_comments':functions,'source_files_hashed':len(source),'shell_python_syntax':'pass','gofmt':'pass','external_links_network_checked':False} (evidence/'document-checks.json').write_text(json.dumps(result,ensure_ascii=False,indent=2)+'\n');print(json.dumps(result,ensure_ascii=False,indent=2)) |