[HOUSEKEEPING] Finding broken links in md files and fix them

azure-pipelines.yml

@@ -36,6 +36,10 @@ steps:
       yarn lint
     displayName: "YARN LINT"
 
+  - script: |
+      yarn md-lint
+    displayName: "YARN MARKDOWN LINT"
+
   - script: |
       yarn build
     displayName: "YARN BUILD"

guides/config-file.md

@@ -1,6 +1,6 @@
 # spk-config.yaml
 
-The [`spk-config.yaml`](./spk-config.yaml) consists of three main sections:
+The [`spk-config.yaml`](../spk-config.yaml) consists of three main sections:
 
 1. `introspection`
 2. `infra`
@@ -35,7 +35,7 @@ There are two options to create environment variables:
 A recommended approach is to have a `.env` file in your folder **(make sure it's
 gitignored!)** with all variables and their values.
 
-[Sample `.env`](./.env.example):
+[Sample `.env`](../.env.example):
 
 ```
 INTROSPECTION_STORAGE_ACCESS_KEY="access key"

guides/contributing.md

@@ -40,8 +40,8 @@ ts-node src/index.ts project init # same as running `./spk project init`
 
 ### Implementing Commands
 
-Refer to this [doc](./guides/command-implementation.md) for guidelines for
-implementing commands.
+Refer to this [doc](./command-implementation.md) for guidelines for implementing
+commands.
 
 ### Running Tests
 

guides/infra/spk-infra-generation-pipeline.md

@@ -13,9 +13,7 @@ orchestrator for your Infrastructure Generation workflow using `spk infra`.
    [here](https://github.com/yradsmikham/spk-infra-hld). You should be able to
    create your Infra HLD repo using a scaffolding process via `spk` (i.e.
    `spk infra scaffold`). For more information on how to do that, please refer
-   to the
-   [Cloud Infra Management](https://github.com/CatalystCode/spk/blob/master/docs/cloud-infra-management.md#scaffold)
-   doc.
+   to the [Cloud Infra Management](../cloud-infra-management.md) doc.
 
 ## Setup
 

guides/infra/spk-infra-under-the-hood.md

@@ -82,8 +82,8 @@ directory):
 
 `spk` will extend the capability to clone private repositories using personal
 access tokens (PAT). For more information, please refer to this
-[section](https://github.com/CatalystCode/spk/blob/master/docs/cloud-infra-management.md#authentication)
-of Cloud Infra Management.
+[section](../cloud-infra-management.md#authentication-private-repos) of Cloud
+Infra Management.
 
 ## Future Considerations
 

guides/infra/spk-terragrunt-overview.md

@@ -13,7 +13,7 @@ scaffolding and generation detailed in the
 4. [Multiple Template Environments](#multiple-template-environments)
 5. [Embedding in SPK](#embedding-in-spk)
 6. [Issues with Terragrunt Approach](#issues-with-terragrunt-approach)
-7. [`spk infra` Vision](/SPK-Infra.md)
+7. [`spk infra` Vision](./spk-terragrunt-day-2-scenarios.md)
 
 ## Prerequisites
 

guides/manual-guide-to-rings.md

@@ -6,7 +6,7 @@ This guide presumes that you have set up your `spk` project, and installed all
 necessary pipelines created via `spk project init` (the lifecycle pipeline),
 `spk service create` (build update hld pipeline), and `spk hld init` (manifest
 generation pipeline), and followed the
-[guidelines for creating helm charts](./building-helm-charts-for-spk).
+[guidelines for creating helm charts](./building-helm-charts-for-spk.md).
 
 In `spk`, we offer the concept of a `ring` - a way to route inbound traffic to
 _revisions_ of a service on a Kubernetes cluster via request headers. For

guides/project-service-management-guide.md

@@ -28,7 +28,7 @@ This document describes the workflow for deploying a set of services
 An overview of how these different pieces fit together from an automation
 perspective:
 
-![spk resources](/guides/images/spk-resource-diagram.png "Bedrock SPK Resources")
+![spk resources](./images/spk-resource-diagram.png "Bedrock SPK Resources")
 
 ## Requirements
 
@@ -134,7 +134,7 @@ applied to the Kubernetes cluster by Flux.
   ```
 
 **NOTE** `spk hld` command documentation can be found
-[here](/guides/hld-management.md).
+[here](./hld-management.md).
 
 ### Materialized Manifests Repository
 
@@ -225,7 +225,7 @@ application repositories
   run `install-lifecycle-pipeline` once for each repo.
 
 **NOTE** `spk project` command documentation can be found
-[here](/guides/project-management.md).
+[here](./project-management.md).
 
 #### Adding a Service to a Application Repository
 
@@ -249,7 +249,7 @@ application repositories
   definition in Azure Devops.
 
 **NOTE** `spk service` command documentation can be found
-[here](/guides/service-management.md).
+[here](./service-management.md).
 
 #### Helm Configuration for SPK
 
@@ -426,7 +426,7 @@ parameters to `spk service create --helm-config-git`:
   ```
 
 **NOTE** `spk service` command documentation can be found
-[here](/guides/service-management.md).
+[here](./service-management.md).
 
 ## Helm Charts
 

guides/service-introspection-onboarding.md

@@ -5,7 +5,7 @@ Service Introspection shows information about a
 
 Service introspection is used via the `spk deployment` commands. More
 information about the commands is available in the command reference
-[here](https://github.com/CatalystCode/spk/blob/master/docs/service-introspection.md).
+[here](./service-introspection.md).
 
 The following diagram shows the main components of service introspection.
 ![spk service introspection diagram](./images/service_introspection.png)
@@ -34,7 +34,7 @@ it or use an existing one.
 **Option 1:**
 
 Use the
-[`spk deployment onboard`](https://github.com/CatalystCode/spk/blob/master/guides/service-introspection.md#onboard)
+[`spk deployment onboard`](https://catalystcode.github.io/spk/commands/#master@deployment_onboard)
 command.
 
 **Option 2:**
@@ -248,10 +248,10 @@ After completing the steps in this guide, you should be able to:
 
 - Validate and verify the `spk-config.yaml` settings and the service
   introspection storage using
-  [`spk deployment validate`](https://github.com/CatalystCode/spk/blob/master/docs/service-introspection.md#validate)
+  [`spk deployment validate`](https://catalystcode.github.io/spk/commands/#master@deployment_validate)
 
 - Get information about your deployment using
-  [`spk deployment get`](https://github.com/CatalystCode/spk/blob/master/docs/service-introspection.md#get)
+  [`spk deployment get`](https://catalystcode.github.io/spk/commands/#master@deployment_get)
 
 - Launch the dashboard to visualize the data using
-  [`spk deployment dashboard`](https://github.com/CatalystCode/spk/blob/master/docs/service-introspection.md#dashboard)
+  [`spk deployment dashboard`](https://catalystcode.github.io/spk/commands/#master@deployment_dashboard)

guides/service-introspection.md

@@ -35,7 +35,7 @@ Global options:
 ## Requirements
 
 Fill out the service introspection settings in your spk config file, for example
-`spk-config.yaml`. [Sample config file](./../../spk-config.yaml).
+`spk-config.yaml`. [Sample config file](../spk-config.yaml).
 
 ```
 introspection:

package.json

@@ -10,6 +10,7 @@
     "build-cmd-docs": "ts-node tools/generateDoc.ts",
     "lint": "eslint 'src/**/*.ts{,x}'",
     "lint-fix": "eslint --fix 'src/**/*.ts{,x}'",
+    "md-lint": "ts-node tools/mdLint.ts",
     "format": "prettier --write 'src/**/*.ts{,x}'",
     "test": "jest --rootDir src --reporters=jest-junit --reporters=default --coverage --coverageReporters=cobertura --coverageReporters=html",
     "test-watch": "jest --watchAll",
@@ -39,6 +40,7 @@
     "jest-junit": "^10.0.0",
     "jest-when": "^2.7.0",
     "lint-staged": ">=10",
+    "markdown-link-check": "^3.8.0",
     "mock-fs": "^4.10.2",
     "nyc": "^14.1.1",
     "pkg": "^4.4.0",

src/lib/pipelines/variableGroup.test.ts

@@ -1,8 +1,5 @@
 /* eslint-disable @typescript-eslint/camelcase */
-import {
-  VariableGroup,
-  VariableGroupParameters,
-} from "azure-devops-node-api/interfaces/TaskAgentInterfaces";
+import { VariableGroupParameters } from "azure-devops-node-api/interfaces/TaskAgentInterfaces";
 import uuid from "uuid/v4";
 import * as azdoClient from "../azdoClient";
 import { readYaml } from "../../config";

tools/generateDoc.ts

@@ -2,12 +2,12 @@ import fs from "fs";
 import path from "path";
 import { CommandBuildElements } from "../src/lib/commandBuilder";
 
-interface ICommand {
+interface Command {
   command: string;
   subcommands: CommandBuildElements[];
 }
 
-interface ICommandElement extends CommandBuildElements {
+interface CommandElement extends CommandBuildElements {
   markdown?: string;
 }
 
@@ -17,9 +17,9 @@ interface ICommandElement extends CommandBuildElements {
 const getAllDecorators = (curDir: string): CommandBuildElements[] => {
   const allFiles = fs.readdirSync(curDir);
   const jsonFiles = allFiles.filter(f => f.endsWith(".json"));
-  const arrJson: ICommandElement[] = [];
+  const arrJson: CommandElement[] = [];
   jsonFiles.forEach(fileName => {
-    const json = require(path.join(curDir, fileName)) as ICommandElement;
+    const json = require(path.join(curDir, fileName)) as CommandElement;
     if (!json.disabled) {
       const mdPath = path.join(
         curDir,
@@ -35,7 +35,7 @@ const getAllDecorators = (curDir: string): CommandBuildElements[] => {
 };
 
 // get sub folders under commands folder.
-const getSubDirectories = (curDir: string) => {
+const getSubDirectories = (curDir: string): string[] => {
   return fs
     .readdirSync(curDir)
     .map(f => path.join(curDir, f))
@@ -46,7 +46,7 @@ const getSubDirectories = (curDir: string) => {
 // command object. e.g `spk infra generate` and
 // `spk deployment dashboard`
 const listCommands = (
-  allCommands: ICommand[]
+  allCommands: Command[]
 ): { [key: string]: CommandBuildElements } => {
   const mainCommands: { [key: string]: CommandBuildElements } = {};
   allCommands.forEach(cmd => {
@@ -68,7 +68,7 @@ const dir = path.join(process.cwd(), "src", "commands");
 const commandDirs = getSubDirectories(dir);
 commandDirs.unshift(dir); // this is needed because `spk init` is outside `commands` folder
 
-const commands: ICommand[] = commandDirs
+const commands: Command[] = commandDirs
   .map(d => {
     return {
       command: path.basename(d),

tools/locateAliases.ts

@@ -2,7 +2,7 @@ import fs from "fs";
 import path from "path";
 import { CommandBuildElements } from "../src/lib/commandBuilder";
 
-interface ICommandElement extends CommandBuildElements {
+interface CommandElement extends CommandBuildElements {
   markdown?: string;
 }
 
@@ -12,9 +12,9 @@ interface ICommandElement extends CommandBuildElements {
 const getAllDecorators = (curDir: string): CommandBuildElements[] => {
   const allFiles = fs.readdirSync(curDir);
   const jsonFiles = allFiles.filter(f => f.endsWith(".json"));
-  const arrJson: ICommandElement[] = [];
+  const arrJson: CommandElement[] = [];
   jsonFiles.forEach(fileName => {
-    const json = require(path.join(curDir, fileName)) as ICommandElement;
+    const json = require(path.join(curDir, fileName)) as CommandElement;
     arrJson.push(json);
   });
   return arrJson;

tools/mdLint.ts

@@ -0,0 +1,38 @@
+import fs from "fs";
+import path from "path";
+import { exec } from "../src/lib/shell";
+
+// get sub folders under commands folder.
+const getMarkdownFiles = (curDir: string, mds: string[]): void => {
+  fs.readdirSync(curDir).forEach((f) => {
+    const p = path.join(curDir, f);
+    if (fs.lstatSync(p).isDirectory()) {
+      getMarkdownFiles(p, mds);
+    } else if (p.endsWith(".md")) {
+      mds.push(p);
+    }
+  });
+};
+
+const testMd = async (f: string): Promise<void> => {
+  try {
+    await exec("./node_modules/.bin/markdown-link-check", [f]);
+  } catch (e) {
+    console.log(`${f}: ${e.message}`);
+    process.exit(1);
+  }
+};
+
+(async (): Promise<void> => {
+  const dir = path.join(process.cwd(), "guides");
+  const mdFiles: string[] = [];
+  getMarkdownFiles(dir, mdFiles);
+  const promises: Promise<void>[] = [];
+
+  mdFiles.forEach((f) => {
+    promises.push(testMd(f));
+  });
+
+  await Promise.all(promises);
+  process.exit(0);
+})();