spec-up-t 1.3.1 → 1.4.0

package/src/parsers/template-tag-parser.js

@@ -0,0 +1,277 @@
+/**
+ * Template Tag Parser - Functional Style
+ * 
+ * This module provides pure functions for processing template-tag markdown extensions:
+ * - [[def: term, alias]] - Term definitions with optional aliases
+ * - [[ref: term]] - Internal term references
+ * - [[xref: spec, term]] - External specification term references
+ * - [[tref: spec, term, alias1, alias2, ...]] - External term references with multiple aliases
+ * 
+ * The functional approach reduces cognitive complexity and makes functions easier to test
+ * as they are pure functions with clear inputs and outputs.
+ */
+
+const { findExternalSpecByKey } = require('../pipeline/references/external-references-service.js');
+const { lookupXrefTerm } = require('../pipeline/rendering/render-utils.js');
+const { whitespace, htmlComments, contentCleaning, externalReferences } = require('../utils/regex-patterns');
+
+/**
+ * Extracts the current file from token content for source tracking
+ * @param {Object} token - The markdown-it token
+ * @param {Object} globalState - Global state containing fallback currentFile
+ * @returns {string} The source file name
+ */
+function extractCurrentFile(token, globalState) {
+  const content = token.map ? token.map[0] : '';
+  const fileMatch = content && content.match && content.match(htmlComments.fileTracker);
+  return fileMatch ? fileMatch[1] : globalState.currentFile || 'unknown';
+}
+
+/**
+ * Main parsing entry point for template-tag constructs
+ * @param {Object} config - Configuration object containing specs and settings
+ * @param {Object} globalState - Global state object containing definitions, references, etc.
+ * @param {Object} token - The markdown-it token being processed
+ * @param {string} type - The type of construct (def, ref, xref, tref)
+ * @param {string} primary - The primary content/term
+ * @returns {string} The rendered HTML for the construct
+ */
+function parseTemplateTag(config, globalState, token, type, primary) {
+  if (!primary) return;
+
+  const currentFile = extractCurrentFile(token, globalState);
+
+  switch (type) {
+    case 'def':
+      return parseDef(globalState, token, primary, currentFile);
+    case 'xref':
+      return parseXref(config, token);
+    case 'tref':
+      return parseTref(token);
+    default:
+      return parseRef(globalState, primary);
+  }
+}
+
+/**
+ * Processes [[def: term, alias1, alias2, ...]] constructs
+ * Creates definition entries and generates HTML spans with proper IDs
+ * Format: "Primary Alias (alias2, alias3, original-term)" similar to tref
+ * @param {Object} globalState - Global state to store definitions
+ * @param {Object} token - The markdown-it token
+ * @param {string} primary - The primary term content
+ * @param {string} currentFile - The source file containing this definition
+ * @returns {string} HTML span elements with term IDs
+ */
+function parseDef(globalState, token, primary, currentFile) {
+  const termName = token.info.args[0];
+  const aliases = token.info.args.slice(1).filter(Boolean); // Get all aliases after the term
+
+  // Store definition in global state for validation and cross-referencing
+  globalState.definitions.push({
+    term: termName,
+    alias: aliases[0] || null, // First alias, or null if no aliases
+    source: currentFile
+  });
+
+  // Determine the primary display term (first alias if available, otherwise original term)
+  const primaryDisplayTerm = aliases.length > 0 ? aliases[0] : termName;
+
+  // Build the display text format: "Primary (alias1, alias2, original-term)"
+  let displayText = primaryDisplayTerm;
+
+  if (aliases.length > 0) {
+    // Collect all additional terms to show in parentheses
+    const parentheticalContent = [];
+
+    // Add remaining aliases (after the first one used as primary)
+    if (aliases.length > 1) {
+      parentheticalContent.push(...aliases.slice(1));
+    }
+
+    // Add original term if it's different from the primary display term
+    if (termName !== primaryDisplayTerm) {
+      parentheticalContent.push(`<span class='term-local-original-term' title='original term'>${termName}</span>`);
+    }
+
+    // Append parenthetical terms if any exist
+    if (parentheticalContent.length > 0) {
+      displayText += ` <span class='term-local-parenthetical-terms'>(${parentheticalContent.join(', ')})</span>`;
+    }
+  }
+
+  // Generate HTML spans for each term/alias combination
+  // This creates anchor points that can be referenced by links
+  // IDs stay intact - we create an ID for the original term and each alias
+  return token.info.args.reduce((acc, syn) => {
+    // Generate a unique term ID by normalizing the synonym: replace whitespace with hyphens and convert to lowercase. The ID is used for fragment identifier (hash) in the URL, which in turn can be used for an anchor in a web page.
+    const termId = `term:${syn.replace(whitespace.oneOrMore, '-').toLowerCase()}`;
+    return `<span id="${termId}">${acc}</span>`;
+  }, displayText);
+}
+
+/**
+ * Processes [[ref: term]] constructs
+ * Creates internal links to locally defined terms
+ * @param {Object} globalState - Global state to track references
+ * @param {string} primary - The term to reference
+ * @returns {string} HTML anchor element linking to local term
+ */
+function parseRef(globalState, primary) {
+  // Track this reference for validation purposes
+  globalState.references.push(primary);
+
+  // Create internal link to the term definition
+  const termId = primary.replace(whitespace.oneOrMore, '-').toLowerCase();
+  return `<a class="term-reference" href="#term:${termId}">${primary}</a>`;
+}
+
+/**
+ * Processes [[xref: spec, term, alias, ...]] constructs
+ * Creates links to external specification terms with tooltips
+ * Uses primaryDisplayTerm concept: shows first alias if available, otherwise shows the term itself
+ * @param {Object} config - Configuration containing external specs
+ * @param {Object} token - The markdown-it token
+ * @returns {string} HTML anchor element linking to external term
+ */
+function parseXref(config, token) {
+  const externalSpec = findExternalSpecByKey(config, token.info.args[0]);
+  const url = externalSpec?.gh_page || '#';
+  const termName = token.info.args[1];
+  const aliases = token.info.args.slice(2).filter(Boolean); // Get all aliases after the term
+  const term = termName.replace(whitespace.oneOrMore, '-').toLowerCase();
+  const xrefTerm = lookupXrefTerm(token.info.args[0], term);
+
+  // Determine the primary display term (first alias if available, otherwise original term)
+  const primaryDisplayTerm = aliases.length > 0 ? aliases[0] : termName;
+
+  // Build link attributes with both local and external href capabilities
+  let linkAttributes = `class="x-term-reference term-reference" data-local-href="#term:${token.info.args[0]}:${term}" href="${url}#term:${term}"`;
+
+  // Add tooltip content if term definition is available
+  if (xrefTerm && xrefTerm.content) {
+    const cleanContent = xrefTerm.content.replace(contentCleaning.quotes, '&quot;').replace(contentCleaning.newlines, ' ');
+    linkAttributes += ` title="External term definition" data-term-content="${cleanContent}"`;
+  }
+
+  return `<a ${linkAttributes}>${primaryDisplayTerm}</a>`;
+}
+
+/**
+ * Processes [[tref: spec, term, alias, ...]] constructs
+ * Creates external term references with multiple aliases displayed in a readable format
+ * Format: "Primary Alias (alias1, alias2, original-term)"
+ * @param {Object} token - The markdown-it token
+ * @returns {string} HTML span element for external term reference
+ */
+function parseTref(token) {
+  const termName = token.info.args[1];
+  const aliases = token.info.args.slice(2).filter(Boolean); // Get all aliases after the term
+
+  // Determine the primary display term (first alias if available, otherwise original term)
+  const primaryDisplayTerm = aliases.length > 0 ? aliases[0] : termName;
+
+  // Build the display text format: "Primary (alias1, alias2, original-term)"
+  let displayText = primaryDisplayTerm;
+
+  if (aliases.length > 0) {
+    // Collect all additional terms to show in parentheses
+    const parentheticalContent = [];
+
+    // Add remaining aliases (after the first one used as primary)
+    if (aliases.length > 1) {
+      parentheticalContent.push(...aliases.slice(1));
+    }
+
+    // Add original term if it's different from the primary display term
+    if (termName !== primaryDisplayTerm) {
+      parentheticalContent.push(`<span class='term-external-original-term' title='original term'>${termName}</span>`);
+    }
+
+    // Append parenthetical terms if any exist
+    if (parentheticalContent.length > 0) {
+      displayText += ` <span class='term-external-parenthetical-terms'>(${parentheticalContent.join(', ')})</span>`;
+    }
+  }
+
+  const termId = `term:${termName.replace(whitespace.oneOrMore, '-').toLowerCase()}`;
+  const primaryAliasId = aliases.length > 0 ? `term:${aliases[0].replace(whitespace.oneOrMore, '-').toLowerCase()}` : '';
+
+  // Handle cases where we have aliases
+  if (aliases.length > 0 && aliases[0] !== termName) {
+    return `<span data-original-term="${termName}" class="term-external" id="${termId}"><span title="Externally defined as ${termName}" id="${primaryAliasId}">${displayText}</span></span>`;
+  } else {
+    return `<span title="Externally also defined as ${termName}" data-original-term="${termName}" class="term-external" id="${termId}">${displayText}</span>`;
+  }
+}
+
+/**
+ * Parses an `[[xref:...]]` or `[[tref:...]]` string into a structured object.
+ * This function was moved from xtref-utils.js to consolidate parsing logic
+ * and prevent cross-module object mutation.
+ *
+ * @param {string} xtref - Raw reference markup including brackets and prefix.
+ * @returns {{ externalSpec: string, term: string, referenceType: string, firstAlias?: string, aliases: string[] }}
+ */
+function processXTrefObject(xtref) {
+  const referenceTypeMatch = xtref.match(externalReferences.referenceType);
+  const referenceType = referenceTypeMatch ? referenceTypeMatch[1] : 'unknown';
+
+  const parts = xtref
+    .replace(externalReferences.openingTag, '')
+    .replace(externalReferences.closingTag, '')
+    .trim()
+    .split(externalReferences.argsSeparator);
+
+  const xtrefObject = {
+    externalSpec: parts[0].trim(),
+    term: parts[1].trim(),
+    referenceType
+  };
+
+  // Collect all aliases from parts after the term (index 1), trim and filter empties
+  const allAliases = parts.slice(2).map(p => p.trim()).filter(Boolean);
+  
+  // Initialize both tref and xref alias arrays
+  xtrefObject.trefAliases = [];
+  xtrefObject.xrefAliases = [];
+
+  // Store aliases in the appropriate array based on reference type
+  if (referenceType === 'tref') {
+    xtrefObject.trefAliases = allAliases;
+    // Store the first tref alias separately as it has special meaning
+    if (allAliases.length > 0) {
+      xtrefObject.firstTrefAlias = allAliases[0];
+    }
+  } else if (referenceType === 'xref') {
+    xtrefObject.xrefAliases = allAliases;
+    // Store the first xref alias separately as it has special meaning
+    if (allAliases.length > 0) {
+      xtrefObject.firstXrefAlias = allAliases[0];
+    }
+  }
+
+  return xtrefObject;
+}
+
+/**
+ * Creates a template-tag parser function with bound configuration and global state.
+ * This provides a clean interface similar to the class-based approach but with functional benefits.
+ * @param {Object} config - Configuration object
+ * @param {Object} globalState - Global state object
+ * @returns {Function} A parser function that can be called with (token, type, primary)
+ */
+function createTemplateTagParser(config, globalState) {
+  return (token, type, primary) => parseTemplateTag(config, globalState, token, type, primary);
+}
+
+module.exports = {
+  createTemplateTagParser,
+  // Export individual functions for testing purposes
+  parseDef,
+  parseXref,
+  parseTref,
+  parseRef,
+  parseTemplateTag,
+  processXTrefObject
+};

package/src/parsers/template-tag-parser.test.js

@@ -0,0 +1,107 @@
+/**
+ * Template Tag Parser Tests - Functional Style
+ *
+ * These tests verify that the template tag parsing functions work correctly
+ * and maintain backward compatibility while providing better testability.
+ */
+
+const {
+  createTemplateTagParser
+} = require('../pipeline/parsing/create-markdown-parser.js');
+
+// Import functions directly from their modules since they're not exported through index
+const {
+  parseDef,
+  parseRef
+} = require('./template-tag-parser');
+
+// Tests for verifying the template tag parsing functions work correctly
+describe('Template Tag Parsing Functions', () => {
+  let mockConfig, mockGlobal;
+
+  beforeEach(() => {
+    mockConfig = {
+      specs: [{
+        external_specs: [{
+          external_spec: 'test-spec',
+          gh_page: 'https://example.com/spec'
+        }]
+      }]
+    };
+
+    mockGlobal = {
+      definitions: [],
+      references: [],
+      specGroups: {},
+      noticeTitles: {},
+      currentFile: 'test.md'
+    };
+
+    // Set up global state
+    global.definitions = mockGlobal.definitions;
+    global.references = mockGlobal.references;
+    global.specGroups = mockGlobal.specGroups;
+    global.noticeTitles = mockGlobal.noticeTitles;
+  });
+
+  // Test: Can the system parse definition markup into proper HTML?
+  test('should parse definition correctly', () => {
+    const mockToken = {
+      info: { args: ['test-term', 'alias'] }
+    };
+
+    const result = parseDef(mockGlobal, mockToken, 'Test Term', 'test.md');
+
+    expect(result).toContain('id="term:test-term"');
+    expect(result).toContain('id="term:alias"');
+    expect(mockGlobal.definitions).toHaveLength(1);
+    expect(mockGlobal.definitions[0]).toEqual({
+      term: 'test-term',
+      alias: 'alias',
+      source: 'test.md'
+    });
+  });
+
+  // Test: Can the system parse reference markup into proper links?
+  test('should parse reference correctly', () => {
+    const result = parseRef(mockGlobal, 'test-term');
+
+    expect(result).toContain('href="#term:test-term"');
+    expect(result).toContain('class="term-reference"');
+    expect(mockGlobal.references).toContain('test-term');
+  });
+
+  // Test: Does the parser factory create functional parsers?
+  test('createTemplateTagParser should return a working function', () => {
+    const templateTagParser = createTemplateTagParser(mockConfig, mockGlobal);
+
+    expect(typeof templateTagParser).toBe('function');
+
+    const mockToken = {
+      info: { args: ['test-term'] }
+    };
+
+    const result = templateTagParser(mockToken, 'def', 'Test Term');
+    expect(result).toContain('id="term:test-term"');
+  });
+
+  // Test: Are the functions pure and independently testable?
+  test('functions should be pure and testable', () => {
+    // Test that pure functions work independently
+    const testGlobal = { definitions: [], references: [] };
+    const testToken = { info: { args: ['pure-test'] } };
+
+    const result = parseDef(testGlobal, testToken, 'Pure Test', 'test.md');
+
+    expect(result).toContain('id="term:pure-test"');
+    expect(testGlobal.definitions).toHaveLength(1);
+    expect(mockGlobal.definitions).toHaveLength(0); // Original should be unchanged
+  });
+
+  // Test: Can individual functions be imported and used separately?
+  test('individual functions should be importable', () => {
+    // Test that individual functions can be imported and used
+    expect(typeof parseDef).toBe('function');
+    expect(typeof parseRef).toBe('function');
+  });
+});

package/src/pipeline/configuration/configure-starterpack.js

@@ -0,0 +1,200 @@
+/**
+ * Interactive configurator for the Spec-Up-T starter pack.
+ *
+ * The module collects starter metadata from the user, updates the first
+ * spec entry in `specs.json`, and persists the changes. It can be required
+ * programmatically or executed directly from the command line.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const Logger = require('../../utils/logger');
+
+const SPECS_KEY = 'specs';
+const JSON_FILE_PATH = path.resolve(process.cwd(), 'specs.json');
+
+const defaultQuestions = [
+    { field: 'title', prompt: 'Enter title', defaultValue: 'Spec-Up-T Starterpack' },
+    { field: 'description', prompt: 'Enter description', defaultValue: 'Create technical specifications in markdown. Based on the original Spec-Up, extended with Terminology tooling' },
+    { field: 'author', prompt: 'Enter author', defaultValue: 'Trust over IP Foundation' },
+    { field: 'account', prompt: 'Enter account', defaultValue: 'trustoverip' },
+    { field: 'repo', prompt: 'Enter repo', defaultValue: 'spec-up-t-starter-pack' }
+];
+
+/**
+ * Verifies that the specs.json file exists before prompting the user.
+ */
+function assertSpecsFileExists() {
+    if (fs.existsSync(JSON_FILE_PATH)) {
+        return;
+    }
+
+    Logger.error(`Error: ${JSON_FILE_PATH} does not exist.`);
+    process.exit(1);
+}
+
+/**
+ * Reads and parses the specs.json file, providing helpful feedback on failure.
+ *
+ * @returns {object} Parsed JSON contents.
+ */
+function loadSpecsConfig() {
+    try {
+        return JSON.parse(fs.readFileSync(JSON_FILE_PATH, 'utf8'));
+    } catch (error) {
+        Logger.error(`Error: Could not parse ${JSON_FILE_PATH}.`, error.message);
+        process.exit(1);
+    }
+}
+
+/**
+ * Ensures the first spec entry exists and returns it for updates. Exits when the
+ * structure is malformed because continuing would corrupt the file.
+ *
+ * @param {object} config - Parsed configuration object from specs.json.
+ * @returns {{ config: object, primarySpec: object }} The config and its first spec entry.
+ */
+function resolvePrimarySpec(config) {
+    const specs = config[SPECS_KEY];
+
+    if (!Array.isArray(specs) || specs.length === 0 || !specs[0]) {
+        Logger.error(`Error: Invalid JSON structure. "${SPECS_KEY}[0]" is missing.`);
+        process.exit(1);
+    }
+
+    return { config, primarySpec: specs[0] };
+}
+
+/**
+ * Builds the prompt text with the default value appended for clarity.
+ *
+ * @param {string} label - Question label displayed to the user.
+ * @param {string} defaultValue - Value shown as default.
+ * @returns {string} Prompt string formatted for readline.
+ */
+function formatPrompt(label, defaultValue) {
+    return `${label} (${defaultValue}): `;
+}
+
+/**
+ * Collects answers for all configuration questions from stdin/stdout.
+ *
+ * @param {Array<{ field: string, prompt: string, defaultValue: string }>} questions - Questions to ask.
+ * @param {NodeJS.ReadableStream} input - Input stream for readline.
+ * @param {NodeJS.WritableStream} output - Output stream for readline.
+ * @returns {Promise<object>} Map of field names to user answers.
+ */
+function promptForAnswers(questions, input, output) {
+    return new Promise((resolve, reject) => {
+        const rl = readline.createInterface({ input, output });
+        const answers = {};
+        let index = 0;
+
+        const askNext = () => {
+            if (index >= questions.length) {
+                rl.close();
+                resolve(answers);
+                return;
+            }
+
+            const { field, prompt, defaultValue } = questions[index];
+            rl.question(formatPrompt(prompt, defaultValue), answer => {
+                answers[field] = answer ? answer.trim() : defaultValue;
+                index += 1;
+                askNext();
+            });
+        };
+
+        rl.on('error', error => {
+            rl.close();
+            reject(error);
+        });
+
+        askNext();
+    });
+}
+
+/**
+ * Applies the collected answers to the spec configuration, keeping nested
+ * `source` fields isolated from top-level metadata.
+ *
+ * @param {object} primarySpec - The spec entry to mutate.
+ * @param {object} answers - User responses keyed by field.
+ */
+function applyAnswersToSpec(primarySpec, answers) {
+    if (!primarySpec.source) {
+        primarySpec.source = {};
+    }
+
+    Object.entries(answers).forEach(([field, value]) => {
+        if (['account', 'repo'].includes(field)) {
+            primarySpec.source[field] = value;
+            return;
+        }
+
+        primarySpec[field] = value;
+    });
+}
+
+/**
+ * Persists the updated configuration back to specs.json.
+ *
+ * @param {object} config - Configuration object with modifications applied.
+ */
+function persistUpdatedConfig(config) {
+    try {
+        fs.writeFileSync(JSON_FILE_PATH, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+        Logger.success(`Successfully updated ${JSON_FILE_PATH}.`);
+    } catch (error) {
+        Logger.error(`Error: Could not update ${JSON_FILE_PATH}.`, error.message);
+        process.exit(1);
+    }
+}
+
+/**
+ * Runs the interactive configuration workflow.
+ *
+ * @param {object} [options]
+ * @param {Array} [options.questions] - Override the default question set.
+ * @param {NodeJS.ReadableStream} [options.input] - Custom input stream for testing.
+ * @param {NodeJS.WritableStream} [options.output] - Custom output stream for testing.
+ * @returns {Promise<void>}
+ */
+async function runStarterpackConfigurator({
+    questions = defaultQuestions,
+    input = process.stdin,
+    output = process.stdout
+} = {}) {
+    assertSpecsFileExists();
+
+    Logger.info(`\nWelcome to the Spec-Up-T Starterpack configuration tool!\n` +
+        '\nYou will be asked a series of questions to customize your project.\n' +
+        "Here’s what each field means:\n" +
+        '- "Title": The name of your project.\n' +
+        '- "Description": A brief explanation of your project.\n' +
+        '- "Author": The name of the person or organization creating the project.\n' +
+        '- "Account": The GitHub account or organization where the repository will be hosted.\n' +
+        '- "Repo": The name of the GitHub repository.\n\n' +
+        'Press Enter to accept the default value shown in parentheses.\n'
+    );
+
+    try {
+        const answers = await promptForAnswers(questions, input, output);
+        const { config, primarySpec } = resolvePrimarySpec(loadSpecsConfig());
+        applyAnswersToSpec(primarySpec, answers);
+        persistUpdatedConfig(config);
+    } catch (error) {
+        Logger.error('Configuration aborted due to an unexpected error.', error.message);
+        process.exit(1);
+    }
+}
+
+if (process.env.SPEC_UP_T_CONFIGURATOR_AUTORUN !== 'false') {
+    runStarterpackConfigurator();
+}
+
+module.exports = {
+    runStarterpackConfigurator
+};

package/src/{create-external-specs-list.js → pipeline/configuration/create-external-specs-list.js}

@@ -12,9 +12,11 @@
  *         Returns a message indicating no specifications were found if the configuration is invalid or empty.
  */
 
+const Logger = require('../../utils/logger.js');
+
 module.exports = function createExternalSpecsList(config) {
     if (!config?.specs?.length || !Array.isArray(config.specs)) {
-        console.warn('❌ Invalid config format. Expected an object with a specs array.');
+        Logger.warn('Invalid config format. Expected an object with a specs array.');
         return '<p>No external specifications found.</p>';
     }
 
@@ -29,24 +31,23 @@ module.exports = function createExternalSpecsList(config) {
         return '<p>No external specifications found.</p>';
     }
 
-    let html = '<ul class="list-group">';
+    let html = '<div class="external-specs-list">';
+    html += '<ul class="list-unstyled">';
 
     externalSpecs.forEach(spec => {
         html += `
-      <li class="list-group-item border-0 p-0 ps-3">
-        <p>
-          ${spec.external_spec}:
-          <a href="${spec.url}" target="_blank" class="">
-            <i class="fa fa-link"></i> URL
-          </a>
-          <a href="${spec.gh_page}" target="_blank" class="">
-            <i class="fa fa-github"></i> GitHub Page
+      <li class="mb-2">
+        <div class="d-flex align-items-center">
+          <i class="bi bi-diagram-3 me-2"></i>
+          <a href="${spec.url}" target="_blank" class="text-decoration-none">${spec.external_spec}</a>
+          <a href="${spec.gh_page}" target="_blank" class="ms-2 btn btn-sm btn-light">
+            <i class="bi bi-github"></i>
           </a>
-        </p>
+        </div>
       </li>
     `;
     });
 
-    html += '</ul>';
+    html += '</ul></div>';
     return html;
 };