Input Option for DirTag Section (#9)

- Introduce optional input parameter dirTagSectionRegex
- Use previous tag as fallback
- Use this Regexp to split the documentation

README.md

@@ -32,6 +32,7 @@ jobs:
           # multiple paths are separated by whitespace or ','
           userDocsDirs: paths/to/ your/doc/dir relative/to/repo/root
           # Optional inputs with defaults:
+          dirTagSectionRegex: /Related Files and Folders/i
           # Check userDocsDirs recursively.
           recurseUserDocDirs: false
           # File extensions for files to be considered documentation.

__tests__/main.test.ts

@@ -110,6 +110,8 @@ describe('action', () => {
           return 'true'
         case 'srcFileExtensions':
           return 'ts,cpp  xyz'
+        case 'dirTagSectionRegex':
+          return '/other stuff/i'
         default:
           return ''
       }
@@ -125,7 +127,8 @@ describe('action', () => {
     expect(getInputMock).toHaveBeenCalledWith('recurseUserDocDirs')
     expect(getInputMock).toHaveBeenCalledWith('docFileExtensions')
     expect(getInputMock).toHaveBeenCalledWith('srcFileExtensions')
-    expect(getInputMock).toHaveBeenCalledTimes(5)
+    expect(getInputMock).toHaveBeenCalledWith('dirTagSectionRegex')
+    expect(getInputMock).toHaveBeenCalledTimes(6)
 
     // Logs from run()
     expect(infoMock).toHaveBeenCalledWith(
@@ -141,6 +144,9 @@ describe('action', () => {
     expect(infoMock).toHaveBeenCalledWith(
       `User doc files:${docfiles.reduce((acc, a) => `${acc}\n  ${a}`, '')}`
     )
+    expect(infoMock).toHaveBeenCalledWith(
+      `Regular expression identifying directory tag section: /other stuff/i`
+    )
     expect(infoMock).toHaveBeenCalledWith(`Changed files:\n  ${changedFile}`)
 
     // Logs from checkDocumentation()

__tests__/testData/recursionStart/sub/dummyDoc.md

@@ -4,7 +4,7 @@ This file dummyDoc.md is for unit tests in __tests__/ like e.g. fakeName.cpp or
 The file main.ts shall be mentioned here and below.
 All tags that do not exist should contain 'fake' to help the unit tests.
 
-## Related files and folders
+## Other Stuff to Look at
 - fake/path/
 - main.ts
 - utils.ts

action.yml

@@ -17,9 +17,13 @@ inputs:
     required: true
     default: 'docs'
   recurseUserDocDirs:
-    description: 'Whether to also look for user doc files in all subdirectories of the given directories'
+    description: 'Whether to also look for user doc files in all subdirectories of the given directories.'
     required: false
     default: false
+  dirTagSectionRegex:
+    description: 'The regular expression that is used to identify the section of a documentation file where the tool starts looking for directory tags.'
+    required: false
+    default: '/Related Files and Folders/i'
   docFileExtensions:
     description: 'File extensions that are considered for doc files.'
     required: false

src/main.ts

@@ -41,16 +41,27 @@ function extractFileTags(
 
 /**
  * Get the list of directory tags in the given file.
- * Directory tags are only considered after the string "Related Files and Folders".
+ * Directory tags are only considered after the pattern given in dirTagSectionRegexStr.
  * A directory tag is defined as a string of non white space characters that ends on '/'.
  * @param fileContent Content of a file given as string.
+ * @param dirTagSectionRegexStr String representation of the regex used to identify the part where directory tags are expected.
  * @return String[] of tags.
  */
-function extractDirectoryTags(fileContent: string): string[] {
+function extractDirectoryTags(
+  fileContent: string,
+  dirTagSectionRegexStr: string
+): string[] {
+  // Decompose the provided regex string into the pattern [1] and potential parameters [2]
+  const decomposedRegex = dirTagSectionRegexStr.match(/\/(.+)\/(.*)/)
+  // if any of the decomposed elements is null insert the empty string
+  const dirTagSectionRegex = new RegExp(
+    decomposedRegex?.[1] ?? '',
+    decomposedRegex?.[2] ?? ''
+  )
   return Array.from(
     fileContent
       // Case insensitive match. Take everything behind the tag
-      .split(/Related Files and Folders/i)[1]
+      .split(dirTagSectionRegex)[1]
       // If there is nothing after the tag default to undefined and thus to []
       // Else match anything that ends on a '/'
       // \S = anything but whitespace
@@ -61,15 +72,19 @@ function extractDirectoryTags(fileContent: string): string[] {
 
 /**
  * Checks that if any tagged source file was changed, its corresponding doc file was changed too.
- * @param userdocs - An array of paths to documentation files.
- * @param changes - An array of paths to files that have been changed.
+ * @param userdocs An array of paths to documentation files.
+ * @param changes An array of paths to files that have been changed.
+ * @param docFileExtensions File extensions for documentation files.
+ * @param srcFileExtensions File extensions for source files.
+ * @param dirTagSectionRegexStr String representation of the regex used to identify the part where directory tags are expected.
  * @returns An exit code: 0 if no errors were found, 1 if errors were found.
  */
 function checkDocumentation(
   userdocs: string[],
   changes: string[],
   docFileExtensions: string[],
-  srcFileExtensions: string[]
+  srcFileExtensions: string[],
+  dirTagSectionRegexStr: string
 ): { unchangedDoc: Map<string, string[]>; unknownTags: Map<string, string[]> } {
   const unchangedDoc = new Map<string, string[]>()
   const unknownTags = new Map<string, string[]>()
@@ -79,7 +94,10 @@ function checkDocumentation(
   for (const docfile of userdocs) {
     const fileContent = fs.readFileSync(docfile, 'utf-8')
     let fileTags = extractFileTags(fileContent, srcFileExtensions)
-    const directoryTags: string[] = extractDirectoryTags(fileContent)
+    const directoryTags: string[] = extractDirectoryTags(
+      fileContent,
+      dirTagSectionRegexStr
+    )
     core.debug(
       `Found tags in ${docfile}: | File Tags: ${fileTags} | Directory Tags: ${directoryTags} |`
     )
@@ -297,6 +315,7 @@ async function getChangedFiles(ghToken: string): Promise<string[]> {
 /**
  * Get list of doc files in the immediate directory. No recursion!
  * @param directories Array of directory paths to search for documentation files.
+ * @param docExtensions File extensions for documentation files.
  * @param recursive If true subdirectories are also searched.
  * @return Array of paths to directory files.
  */
@@ -382,6 +401,12 @@ export async function run(): Promise<void> {
       `User doc files:${docFiles.reduce((acc, a) => `${acc}\n  ${a}`, '')}`
     )
 
+    const dirTagSectionRegexStr =
+      core.getInput('dirTagSectionRegex') || '/Related Files and Folders/i'
+    core.info(
+      `Regular expression identifying directory tag section: ${dirTagSectionRegexStr}`
+    )
+
     // Get changes from the PR
     const changedFiles = await getChangedFiles(ghToken)
     core.info(
@@ -393,7 +418,8 @@ export async function run(): Promise<void> {
       docFiles,
       changedFiles,
       docFileExtensions,
-      srcFileExtensions
+      srcFileExtensions,
+      dirTagSectionRegexStr
     )
 
     // ------------------------- Process the analysis -------------------------