Source location in output for local builds

.ci/asciidoc-converter/build_standard_debug.bat

@@ -0,0 +1,3 @@
+mkdir ..\..\sdpi-documents
+mkdir ..\..\sdpi-documents\sdpi-standard-debug
+gradlew.bat run --args="--input-file ../../asciidoc/sdpi-standard.adoc --output-folder ../../sdpi-documents/sdpi-standard-debug --backend html --debug"

.ci/asciidoc-converter/src/main/kotlin/org/sdpi/AsciidocConverter.kt

@@ -42,6 +42,12 @@ class ConverterOptions(
      */
     val generateTestOutput: Boolean = false,
 
+    /**
+     * When true, features implemented in pre- and post-processors
+     * are disabled so source file and line numbers are accurate.
+     */
+    val debugMode: Boolean = false,
+
     /**
      * Folder where extracts (requirements, use-cases, etc.) should
      * be placed. If null, the extracts won't be written.
@@ -97,7 +103,6 @@ class AsciidocConverter(
             .sourcemap(true)
             .headerFooter(!conversionOptions.generateTestOutput)
             .toStream(outputFile).build()
-        val bEnablePrePostProcessing = true
 
         val asciidoctor = Asciidoctor.Factory.create()
 
@@ -158,12 +163,16 @@ class AsciidocConverter(
         asciidoctor.javaExtensionRegistry().inlineMacro(TransactionReferenceMacroProcessor(infoCollector))
         asciidoctor.javaExtensionRegistry().inlineMacro(ProfileReferenceMacroProcessor(infoCollector))
 
-        if (bEnablePrePostProcessing) {
+        // Essential for document processing but breaks line number and source references, so
+        // we disable when debugging to simplify troubleshooting.
+        if (!conversionOptions.debugMode) {
             asciidoctor.javaExtensionRegistry().preprocessor(IssuesSectionPreprocessor(conversionOptions.githubToken))
             asciidoctor.javaExtensionRegistry().preprocessor(DisableSectNumsProcessor())
         }
 
-        if (bEnablePrePostProcessing) {
+        // Essential for document processing but breaks line number and source references, so
+        // we disable when debugging to simplify troubleshooting.
+        if (!conversionOptions.debugMode) {
             println("Enable pre post processing.")
             val referenceSanitizerPre = ReferenceSanitizerPreprocessor(anchorReplacements)
             asciidoctor.javaExtensionRegistry().preprocessor(referenceSanitizerPre)

.ci/asciidoc-converter/src/main/kotlin/org/sdpi/ConvertAndVerifySupplement.kt

@@ -52,6 +52,9 @@ class ConvertAndVerifySupplement : CliktCommand("convert-supplement") {
     private val testGenerator by option("--test", help = "Writes document without headers for test output")
         .flag(default = false)
 
+    private  val debugGenerator by option("--debug", help="Simplified processing for accurate source and line number diagnostics")
+        .flag(default = false)
+
     override fun run() {
         runCatching {
             val asciidocErrorChecker = AsciidocErrorChecker()
@@ -74,6 +77,7 @@ class ConvertAndVerifySupplement : CliktCommand("convert-supplement") {
                     outputFormat = backend,
                     dumpStructure = dumpStructure,
                     generateTestOutput = testGenerator,
+                    debugMode = debugGenerator,
                 )
             )
             converter.run()

.ci/asciidoc-converter/src/main/kotlin/org/sdpi/asciidoc/Util.kt

@@ -2,6 +2,7 @@ package org.sdpi.asciidoc
 
 import org.apache.logging.log4j.kotlin.loggerOf
 import org.asciidoctor.ast.ContentNode
+import org.asciidoctor.ast.Cursor
 import org.asciidoctor.ast.StructuralNode
 import org.sdpi.asciidoc.extension.Roles
 import org.sdpi.asciidoc.model.BlockOwner
@@ -141,6 +142,20 @@ fun getLocation(block: StructuralNode): String {
     }
 }
 
+fun findSourceLocation(node: ContentNode): String {
+    var current: ContentNode? = node
+
+    while (current != null) {
+        if (current is StructuralNode) {
+            current.sourceLocation?.let { return it.toString() }
+        }
+
+        current = current.parent
+    }
+
+    return "Unknown"
+}
+
 fun getTitleFrom(block: StructuralNode): String {
     if (block.reftext != null) {
         return block.reftext

.ci/asciidoc-converter/src/main/kotlin/org/sdpi/asciidoc/extension/AddQueryTablePlaceholder.kt

@@ -66,7 +66,7 @@ class AddTransactionQueryPlaceholder : BlockMacroProcessor(BLOCK_MACRO_NAME_TRAN
         // Add filter attributes to the table for the tree processor to consume.
         val strProfile = attributes[Roles.Profile.ID.key]
         checkNotNull(strProfile) {
-            logger.error("$BLOCK_MACRO_NAME_TRANSACTION_TABLE missing required attribute '${Roles.Profile.ID.key}'")
+            logger.error("${parent.sourceLocation} -> $BLOCK_MACRO_NAME_TRANSACTION_TABLE missing required attribute '${Roles.Profile.ID.key}'")
         }
         placeholderTable.attributes[Roles.Profile.ID.key] = strProfile
 
@@ -98,7 +98,7 @@ class AddContentModuleQueryPlaceholder : BlockMacroProcessor(BLOCK_MACRO_NAME_CO
         // Add filter attributes to the table for the tree processor to consume.
         val strProfile = attributes[Roles.Profile.ID.key]
         checkNotNull(strProfile) {
-            logger.error("$BLOCK_MACRO_NAME_CONTENT_MODULE_TABLE missing required attribute '${Roles.Profile.ID.key}'")
+            logger.error("${parent.sourceLocation} -> $BLOCK_MACRO_NAME_CONTENT_MODULE_TABLE missing required attribute '${Roles.Profile.ID.key}'")
         }
         placeholderTable.attributes[Roles.Profile.ID.key] = strProfile
 
@@ -125,7 +125,7 @@ class AddOidQueryPlaceholder : BlockMacroProcessor(BLOCK_MACRO_NAME_OID_TABLE) {
         // Add filter attributes to the table for the tree processor to consume.
         val strRootArcs = attributes[TableAttributes.OidTable.ROOT_ARC.key]?.toString()
         checkNotNull(strRootArcs) {
-            logger.error("$BLOCK_MACRO_NAME_OID_TABLE missing required attribute '${TableAttributes.OidTable.ROOT_ARC.key}'")
+            logger.error("${parent.sourceLocation} -> $BLOCK_MACRO_NAME_OID_TABLE missing required attribute '${TableAttributes.OidTable.ROOT_ARC.key}'")
         }
         placeholderTable.attributes[TableAttributes.OidTable.ROOT_ARC.key] = strRootArcs
 

.ci/asciidoc-converter/src/main/kotlin/org/sdpi/asciidoc/extension/BibliographyCollector.kt

@@ -44,26 +44,26 @@ class BibliographyCollector : Treeprocessor() {
                 val mParsed = reBibParser.find(strItem)
                 checkNotNull(mParsed)
                 {
-                    "${getLocation(bibEntry)} invalid format '$strItem'".also { logger.error { it } }
+                    "${document.sourceLocation} -> ${getLocation(bibEntry)} invalid format '$strItem'".also { logger.error { it } }
                 }
                 val strRef = mParsed.groups["ref"]?.value
                 checkNotNull(strRef)
                 {
-                    "${getLocation(bibEntry)} missing reference".also { logger.error { it } }
+                    "${document.sourceLocation} -> ${getLocation(bibEntry)} missing reference".also { logger.error { it } }
                 }
                 val strRefText = mParsed.groups["reftxt"]?.value
                 checkNotNull(strRefText)
                 {
-                    "${getLocation(bibEntry)} missing reference text for $strRef".also { logger.error { it } }
+                    "${document.sourceLocation} -> ${getLocation(bibEntry)} missing reference text for $strRef".also { logger.error { it } }
                 }
                 val strSource = mParsed.groups["entry"]?.value
                 checkNotNull(strSource)
                 {
-                    "${getLocation(bibEntry)} missing reference source for $strRef".also { logger.error { it } }
+                    "${document.sourceLocation} -> ${getLocation(bibEntry)} missing reference source for $strRef".also { logger.error { it } }
                 }
 
                 if (bibliographyEntries.contains(strRef)) {
-                    "${getLocation(bibEntry)} duplicate reference id $strRef".also { logger.error { it } }
+                    "${document.sourceLocation} -> ${getLocation(bibEntry)} duplicate reference id $strRef".also { logger.error { it } }
                 }
                 bibliographyEntries[strRef] = BibliographyEntry(strRef, strRefText, strSource)
             }

.ci/asciidoc-converter/src/main/kotlin/org/sdpi/asciidoc/extension/ContentModuleIncludeProcessor.kt

@@ -32,7 +32,7 @@ class ContentModuleIncludeProcessor : BlockMacroProcessor(BLOCK_MACRO_NAME_INCLU
     ): Any? {
         val (strProfileId, strProfileOptionId) = findProfileId(parent)
         checkNotNull(strProfileId) {
-            logger.error("$BLOCK_MACRO_NAME_INCLUDE_CONTENT_MODULE requires a ancestor block within the 'profile' role")
+            logger.error("${parent.sourceLocation} -> $BLOCK_MACRO_NAME_INCLUDE_CONTENT_MODULE requires a ancestor block within the 'profile' role")
         }
 
         val strActor = attributes[ContentModuleAttributes.ACTOR.key]?.toString() ?: findIdFromParent(
@@ -41,16 +41,16 @@ class ContentModuleIncludeProcessor : BlockMacroProcessor(BLOCK_MACRO_NAME_INCLU
             ContentModuleAttributes.ACTOR.key
         )
         checkNotNull(strActor) {
-            logger.error("$BLOCK_MACRO_NAME_INCLUDE_CONTENT_MODULE requires an ${ContentModuleAttributes.ACTOR.key} attribute or parent container")
+            logger.error("${parent.sourceLocation} -> $BLOCK_MACRO_NAME_INCLUDE_CONTENT_MODULE requires an ${ContentModuleAttributes.ACTOR.key} attribute or parent container")
         }
 
         val strObligation = attributes[ContentModuleAttributes.OBLIGATION.key]?.toString()
         checkNotNull(strObligation) {
-            logger.error("$BLOCK_MACRO_NAME_INCLUDE_CONTENT_MODULE requires an ${ContentModuleAttributes.OBLIGATION.key} attribute")
+            logger.error("${parent.sourceLocation} -> $BLOCK_MACRO_NAME_INCLUDE_CONTENT_MODULE requires an ${ContentModuleAttributes.OBLIGATION.key} attribute")
         }
         val obligation = parseObligation(strObligation)
         checkNotNull(obligation) {
-            logger.error("$BLOCK_MACRO_NAME_INCLUDE_CONTENT_MODULE requires valid ${ContentModuleAttributes.OBLIGATION.key} attribute")
+            logger.error("${parent.sourceLocation} -> $BLOCK_MACRO_NAME_INCLUDE_CONTENT_MODULE requires valid ${ContentModuleAttributes.OBLIGATION.key} attribute")
         }
 
         val strPlaceholderName = attributes[ContentModuleAttributes.PLACEHOLDER_NAME.key]?.toString()

.ci/asciidoc-converter/src/main/kotlin/org/sdpi/asciidoc/extension/DocumentAnchorCollector.kt

@@ -48,7 +48,7 @@ class DocumentAnchorCollector : Treeprocessor() {
 
         if (strId != null) {
             if (knownAnchors.contains(strId)) {
-                logger.error("Found duplicate id $strId; ids should be unique.")
+                logger.error("${block.sourceLocation} -> Found duplicate id $strId; ids should be unique.")
             }
             knownAnchors[strId] = strRefText.toString()
         }

.ci/asciidoc-converter/src/main/kotlin/org/sdpi/asciidoc/extension/PopulateTables.kt

@@ -175,7 +175,7 @@ class PopulateTables(private val docInfo: SdpiInformationCollector, private val
 
         val strProfile = table.attributes[Roles.Profile.ID.key]?.toString()
         checkNotNull(strProfile) {
-            logger.error("Table missing required attribute '${Roles.Profile.ID.key}'")
+            logger.error("${table.sourceLocation} -> Table missing required attribute '${Roles.Profile.ID.key}'")
         }
 
         val strProfileOption = table.attributes[Roles.Profile.ID_PROFILE_OPTION.key]?.toString()
@@ -188,7 +188,7 @@ class PopulateTables(private val docInfo: SdpiInformationCollector, private val
 
         val profile: SdpiProfile? = docInfo.getProfile(strProfile)
         checkNotNull(profile) {
-            logger.error("Unknown profile $strProfile")
+            logger.error("${table.sourceLocation} -> Unknown profile $strProfile")
         }
 
         val tableBuilder = TransactionTableBuilder(this, table, strActorId == null)
@@ -197,7 +197,7 @@ class PopulateTables(private val docInfo: SdpiInformationCollector, private val
         if (strActorId != null) {
             val actor = profile.getActor(strActorId)
             checkNotNull(actor) {
-                logger.error("Actor $strActorId is not defined in profile $strProfile")
+                logger.error("${table.sourceLocation} -> Actor $strActorId is not defined in profile $strProfile")
             }
             addActorTransactions(tableBuilder, profile, actor, profileFilter)
         } else {
@@ -220,7 +220,7 @@ class PopulateTables(private val docInfo: SdpiInformationCollector, private val
                 val strTransactionId = transactionReference.transactionId
                 val transaction: SdpiTransaction? = getTransaction(transactionReference)
                 checkNotNull(transaction) {
-                    logger.error("Unknown transaction id $strTransactionId")
+                    logger.error("${tableBuilder.table.sourceLocation} -> Unknown transaction id $strTransactionId")
                 }
 
                 val obligationsForTransaction =
@@ -300,7 +300,7 @@ class PopulateTables(private val docInfo: SdpiInformationCollector, private val
                 val strRefId = ref.contentModuleId
                 val module: SdpiContentModule? = getContentModule(ref)
                 checkNotNull(module) {
-                    logger.error("Unknown content-module id $strRefId")
+                    logger.error("${tableBuilder.table.sourceLocation} -> Unknown content-module id $strRefId")
                 }
 
                 tableBuilder.addRow(
@@ -318,7 +318,7 @@ class PopulateTables(private val docInfo: SdpiInformationCollector, private val
                 val strRefId = ref.contentModuleId
                 val module: SdpiContentModule? = getContentModule(ref)
                 checkNotNull(module) {
-                    logger.error("Unknown content-module id $strRefId")
+                    logger.error("${tableBuilder.table.sourceLocation} -> Unknown content-module id $strRefId")
                 }
 
                 tableBuilder.addRow(
@@ -355,7 +355,7 @@ class PopulateTables(private val docInfo: SdpiInformationCollector, private val
 
         val strRootArcs = table.attributes[TableAttributes.OidTable.ROOT_ARC.key]?.toString()
         checkNotNull(strRootArcs) {
-            logger.error("$BLOCK_MACRO_NAME_OID_TABLE missing required attribute '${TableAttributes.OidTable.ROOT_ARC.key}'")
+            logger.error("${table.sourceLocation} -> $BLOCK_MACRO_NAME_OID_TABLE missing required attribute '${TableAttributes.OidTable.ROOT_ARC.key}'")
         }
 
         val oidsToTable = mutableListOf<SdpiOidReference>()
@@ -376,9 +376,9 @@ class PopulateTables(private val docInfo: SdpiInformationCollector, private val
             } else if (strArc == WellKnownOid.DEV_REQUIREMENT.id) {
                 gatherRequirementOids(oidsToTable)
             } else if (strArc == "use-case-support") {
-                gatherUseCaseSupportOids(oidsToTable)
+                gatherUseCaseSupportOids(table, oidsToTable)
             } else {
-                logger.error("Oid tables don't support $strArc (yet?)")
+                logger.error("${table.sourceLocation} -> Oid tables don't support $strArc (yet?)")
             }
         }
 
@@ -484,12 +484,12 @@ class PopulateTables(private val docInfo: SdpiInformationCollector, private val
         }
     }
 
-    private fun gatherUseCaseSupportOids(oidsToTable: MutableList<SdpiOidReference>) {
+    private fun gatherUseCaseSupportOids(table:Table, oidsToTable: MutableList<SdpiOidReference>) {
         for (profile in docInfo.profiles()) {
             for(support in profile.useCaseSupport) {
                 val useCase = docInfo.useCases()[support.useCaseId]
                 checkNotNull(useCase) {
-                    logger.error("Unknown use case `${support.useCaseId}` supported by profile `${profile.profileId}`")
+                    logger.error("${table.sourceLocation} -> Unknown use case `${support.useCaseId}` supported by profile `${profile.profileId}`")
                 }
                 for(strOid in support.oid) {
                     val oid = SdpiOidReference(