blob: fe3046dd0fa152f58b79f4b5c6b9be98e3de557b [file] [log] [blame]
// Copyright 2020 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
import 'dart:async';
import 'dart:io';
import 'package:doc_checker/graph.dart';
import 'package:path/path.dart' as path;
import 'package:doc_checker/errors.dart';
import 'package:doc_checker/projects.dart';
import 'package:doc_checker/link_verifier.dart';
/// Information about the document containing the link to check.
class DocContext {
String baseDir;
String docLabel;
Node node;
Iterable<String> links;
DocContext(this.baseDir, this.docLabel, this.node, this.links);
/// LinkChecker applies the collection of checks to a link
/// to make sure it is valid and follows the coding practices
/// for Fuchsia
class LinkChecker {
/// Top level paths to the published doc site that any page can link to.
/// Links to other locations have to be allowed by adding the source doc
/// page to _filesAllowedToLinkToPublishedDocs.
static const List<String> _publishedLinksAllowed = ['', 'reference'];
/// Files that are allowed to link to the documentation host site.
static const List<String> _filesAllowedToLinkToPublishedDocs = [''];
/// Files that are allowed to be linked in docs. These are non-markdown files
/// that are referenced by markdown documents.
static const List<String> _filesAllowedUsingURI = ['OWNERS'];
/// The fuchsia Gerrit host. Used to check if link should be http or file based.
static const String _fuchsiaGerritHost = '';
/// Documentation site. Used to determine if a link should be to this host or file based.
static const String _publishedDocsHost = '';
/// Different ways of pointing to the master branch of a project in a Gerrit
/// link.
static const List<String> _masterSynonyms = [
final List<Error> errors = <Error>[];
final List<Link<String>> inTreeLinks = [];
final List<Link<String>> outOfTreeLinks = [];
String rootDir;
String docsDir;
String docsProject;
bool checkLocalLinksOnly = false;
LinkChecker(this.rootDir, this.docsDir, this.docsProject);
/// Checks out of tree link. Returns true if isError.
/// Error is added to errors list.
Future<bool> checkOutOfTreeLinks(
Iterable<Link<String>> additionalLinks) async {
bool foundError = false;
// Verify http links pointing outside the tree.
if (!checkLocalLinksOnly) {
await verifyLinks(outOfTreeLinks, (Link<String> link, bool isValid) {
if (!isValid) {
Error(ErrorType.brokenLink, link.payload, link.uri.toString()));
foundError = true;
return foundError;
Future<bool> checkInTreeLinks() async {
bool foundError = false;
// Verify http links pointing inside the tree just by checking to see if the
// path exists, as HTTP calls would be unnecessarily expensive here.
for (Link<String> link in inTreeLinks) {
final File possibleFile = File.fromUri(link.uri);
final Directory possibleDir = Directory.fromUri(link.uri);
* Check that the link is one of:
a file that exists
a directory that exists outside the /docs/ directory, such as a source directory.foundError
a directory within the docs directory and it has a file in that directory.
if (possibleFile.existsSync()) {
} else if (possibleDir.existsSync()) {
// Check for or being outside the /docs/ directory.
if (possibleDir.path.contains('/docs/') &&
!File('${possibleDir.path}/').existsSync()) {
ErrorType.invalidLinkToDirectory, link.payload, link.toString()));
foundError = true;
} else {
// Neither the file nor the directory exist, record and error.
errors.add(Error(ErrorType.brokenLink, link.payload, link.toString()));
foundError = true;
return foundError;
/// Checks whether the URI points to the master branch of a Gerrit (i.e.,
/// project.
bool onGerritMaster(Uri uri) {
final int index = uri.pathSegments.indexOf('+');
if (index == -1 || index == uri.pathSegments.length - 1) {
return false;
final String subPath = uri.pathSegments.sublist(index + 1).join('/');
for (String branch in _masterSynonyms) {
if (subPath.startsWith(branch)) {
return true;
return false;
/// Checks the given link, returning true if there is an error.
/// The error is added to the errors field.
bool checkLink(DocContext doc, String link,
Function(String docPath, DocContext doc, String linkLabel) onNewEdge) {
// Parse link to URI
Uri uri;
try {
uri = Uri.parse(link);
} on FormatException {
errors.add(Error(ErrorType.invalidUri, doc.docLabel, link));
return true;
// Check URI that have a scheme. Files are handled with the scheme-less.
if (uri.hasScheme && uri.scheme != 'file') {
// Ignore non http schemes.
if (uri.scheme != 'http' && uri.scheme != 'https') {
return false;
final bool linkToFuchsiaGerritHost = uri.authority == _fuchsiaGerritHost;
final bool linkToPublishedDocsHost = uri.authority == _publishedDocsHost;
final String project =
uri.pathSegments.isEmpty ? '' : uri.pathSegments[0];
// Check links back to the gerrit host server.
if (linkToFuchsiaGerritHost) {
if (onGerritMaster(uri) && project == docsProject) {
// Check for doc exception Files
final int index = uri.pathSegments.indexOf('docs');
String subPath = uri.path;
if (index >= 0) {
subPath = uri.pathSegments[uri.pathSegments.length - 1];
if (!_filesAllowedUsingURI.contains(subPath)) {
ErrorType.convertHttpToPath, doc.docLabel, uri.toString()));
return true;
} else if (!validProjects.contains(project)) {
Error(ErrorType.obsoleteProject, doc.docLabel, uri.toString()));
return true;
return false;
// Check links to the published docs server.
if (linkToPublishedDocsHost &&
!_publishedLinksAllowed.contains(project)) {
if (!_filesAllowedToLinkToPublishedDocs
.contains(path.basename(doc.docLabel))) {
Error(ErrorType.convertHttpToPath, doc.docLabel, uri.toString()));
return true;
} else {
outOfTreeLinks.add(Link(uri, doc.docLabel));
return false;
} else {
// Handle non-schemed URI.
final List<String> parts = uri.path.split('#');
final String location = parts[0];
// TODO(wilkinsonclay): Add anchor name checks.
if (location.isEmpty) {
return false;
final String rootRelPath = location.startsWith('/')
? location.substring(1)
: path.relative(path.join(doc.baseDir, location), from: rootDir);
final String absPath = path.join(rootDir, rootRelPath);
final String linkLabel = '//$rootRelPath';
final Uri localUri = Uri.parse('file://$absPath');
// Callback for the graph building.
if (onNewEdge != null) {
onNewEdge(absPath, doc, linkLabel);
// Links that reference a parent dir past root dir have a path of / when parsed to URIs.
// When this happens, the rootRelPath is empty, so flag this as an invalid path.
if (rootRelPath.isEmpty) {
errors.add(Error(ErrorType.invalidRelativePath, doc.docLabel, link));
return true;
if (location.contains('../') &&
!localUri.toString().startsWith('file://$docsDir')) {
.add(Error(ErrorType.invalidRelativePath, doc.docLabel, location));
return true;
inTreeLinks.add(Link(localUri, doc.docLabel));
return false;
return false;
Future<bool> check(
Iterable<DocContext> docList,
Iterable<Link<String>> additionalOutOfTreeLinks,
Function(String docPath, DocContext doc, String linkLabel)
onNewEdge) async {
bool foundError = false;
for (DocContext doc in docList) {
for (String link in doc.links) {
foundError |= checkLink(doc, link, onNewEdge);
foundError |= await checkInTreeLinks();
foundError |= await checkOutOfTreeLinks(additionalOutOfTreeLinks);
return foundError;