Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 | 1x 1x 25x 25x 6x 8x 3x 3x 34x 34x 34x 34x 34x 15x 34x 20x 11x 20x 20x 14x 2x 12x 12x 12x 12x 12x 2x 10x 5x 5x 5x 5x 5x 1x 5x 12x 12x 12x 12x 12x 12x 7x 12x 28x 28x 28x 1x 27x 27x 34x 34x 27x 1x | /**
* @file Utility helpers for identifying, parsing, and aggregating external term references (xref/tref).
*
* These functions were previously embedded in the monolithic `collect-external-references` module.
* Splitting them into a dedicated utility keeps the collection pipeline focused on orchestration
* and makes the primitives easier to reuse in other reference-aware stages.
*/
const { externalReferences, utils } = require('../../utils/regex-patterns');
const Logger = require('../../utils/logger');
/**
* Checks if a specific xtref is present in the markdown content.
*
* @param {{ externalSpec: string, term: string }} xtref - Reference descriptor.
* @param {string} markdownContent - Markdown text to inspect.
* @returns {boolean} True when the reference is found.
*/
function isXTrefInMarkdown(xtref, markdownContent) {
const regexTerm = utils.createXTrefRegex(xtref.externalSpec, xtref.term);
return regexTerm.test(markdownContent);
}
/**
* Finds a reference across multiple markdown files.
*
* @param {{ externalSpec: string, term: string }} xtref - Reference descriptor.
* @param {Map<string, string>} fileContents - Markdown contents keyed by filename.
* @returns {boolean} True when the reference is found in any file.
*/
function isXTrefInAnyFile(xtref, fileContents) {
for (const content of fileContents.values()) {
if (isXTrefInMarkdown(xtref, content)) {
return true;
}
}
return false;
}
/**
* Adds a pre-parsed xtref object to the aggregated collection.
* This function handles deduplication and source file tracking.
*
* @param {object} xtrefObject - Pre-parsed xtref object from template-tag-parser
* @param {{ xtrefs: Array<object> }} allXTrefs - Aggregated reference collection
* @param {string|null} filename - Originating filename for bookkeeping
* @param {Array<object>|null} externalSpecs - Array of external_specs from specs.json for validation
* @returns {{ xtrefs: Array<object> }} Updated reference collection
*/
function addXtrefToCollection(xtrefObject, allXTrefs, filename = null, externalSpecs = null) {
const referenceType = xtrefObject.referenceType;
const cleanXTrefObj = { ...xtrefObject };
delete cleanXTrefObj.referenceType;
// Validate that the external spec exists in specs.json configuration
Iif (externalSpecs && Array.isArray(externalSpecs)) {
const externalSpecExists = externalSpecs.some(
spec => spec.external_spec === cleanXTrefObj.externalSpec
);
if (!externalSpecExists) {
const availableSpecs = externalSpecs.map(s => s.external_spec).join(', ');
Logger.error(
`External spec "${cleanXTrefObj.externalSpec}" not found in specs.json configuration. ` +
`Available external specs: ${availableSpecs}. ` +
`Check [[${referenceType}: ${cleanXTrefObj.externalSpec}, ${cleanXTrefObj.term}]] in ${filename || 'unknown file'}`
);
}
}
const existingIndex = allXTrefs?.xtrefs?.findIndex(existingXTref =>
existingXTref.term === cleanXTrefObj.term &&
existingXTref.externalSpec === cleanXTrefObj.externalSpec
);
if (existingIndex === -1) {
if (filename) {
cleanXTrefObj.sourceFiles = [{ file: filename, type: referenceType }];
}
allXTrefs.xtrefs.push(cleanXTrefObj);
return allXTrefs;
}
if (!filename) {
return allXTrefs;
}
const existingXTref = allXTrefs.xtrefs[existingIndex];
// Update the existing entry with new data to handle changes in aliases
// Preserve the existing sourceFiles array and extend it with new entries
const existingSourceFiles = existingXTref.sourceFiles || [];
// Smart merge: Priority is given to tref over xref for properties like aliases
// If the new reference is an xref and existing has tref data, preserve tref properties
const hasExistingTref = existingSourceFiles.some(sf => sf.type === 'tref');
const isNewXref = referenceType === 'xref';
if (hasExistingTref && isNewXref) {
// Don't overwrite tref data with xref data - just merge xref aliases
// Keep existing tref aliases and properties, but add xref aliases
Iif (cleanXTrefObj.xrefAliases && cleanXTrefObj.xrefAliases.length > 0) {
existingXTref.xrefAliases = cleanXTrefObj.xrefAliases;
existingXTref.firstXrefAlias = cleanXTrefObj.firstXrefAlias;
}
} else if (!hasExistingTref && isNewXref) {
// New xref with no existing tref - initialize empty tref arrays
Object.assign(existingXTref, cleanXTrefObj);
Iif (!existingXTref.trefAliases) {
existingXTref.trefAliases = [];
}
} else {
// Update with new tref data (either new tref, or updating existing tref)
Object.assign(existingXTref, cleanXTrefObj);
// Ensure xref arrays exist if not present in new object
Iif (!cleanXTrefObj.xrefAliases && !existingXTref.xrefAliases) {
existingXTref.xrefAliases = [];
}
// Handle properties that should be removed when not present in the new object
if (!cleanXTrefObj.hasOwnProperty('firstTrefAlias') && existingXTref.hasOwnProperty('firstTrefAlias')) {
delete existingXTref.firstTrefAlias;
}
Iif (!cleanXTrefObj.hasOwnProperty('firstXrefAlias') && existingXTref.hasOwnProperty('firstXrefAlias')) {
delete existingXTref.firstXrefAlias;
}
}
// Restore and update the sourceFiles array
existingXTref.sourceFiles = existingSourceFiles;
Eif (filename) {
const newEntry = { file: filename, type: referenceType };
const alreadyTracked = existingXTref.sourceFiles.some(entry =>
entry.file === filename && entry.type === referenceType
);
if (!alreadyTracked) {
existingXTref.sourceFiles.push(newEntry);
}
}
return allXTrefs;
}
/**
* Adds new references discovered in markdown to an aggregated collection.
* This function uses external parsing to maintain separation of concerns
* between parsing and collection logic.
*
* @param {string} markdownContent - Markdown text to scan.
* @param {{ xtrefs: Array<object> }} allXTrefs - Aggregated reference collection.
* @param {string|null} filename - Originating filename for bookkeeping.
* @param {function} processXTrefObject - Parsing function for xtref strings.
* @param {Array<object>|null} externalSpecs - Array of external_specs from specs.json for validation.
* @returns {{ xtrefs: Array<object> }} Updated reference collection.
*/
function addNewXTrefsFromMarkdown(markdownContent, allXTrefs, filename = null, processXTrefObject, externalSpecs = null) {
Iif (!processXTrefObject) {
throw new Error('processXTrefObject function is required. Import from template-tag-parser.');
}
const regex = externalReferences.allXTrefs;
if (!regex.test(markdownContent)) {
return allXTrefs;
}
const xtrefs = markdownContent.match(regex) || [];
xtrefs.forEach(rawXtref => {
const xtrefObject = processXTrefObject(rawXtref);
addXtrefToCollection(xtrefObject, allXTrefs, filename, externalSpecs);
});
return allXTrefs;
}
module.exports = {
isXTrefInMarkdown,
isXTrefInAnyFile,
addXtrefToCollection,
addNewXTrefsFromMarkdown
};
|