spec-up-t 1.3.0 → 1.4.0

package/src/markdown-it/link-enhancement.js

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * Markdown-it Link Enhancement Module
+ * 
+ * This module enhances link rendering by adding path-based attributes to anchor tags.
+ * These attributes can be used for CSS styling or JavaScript behavior based on the
+ * link's destination (domain, path segments, etc.).
+ * 
+ * For example, a link to "https://example.com/docs/api" would get attributes like:
+ * - path-0="example.com"
+ * - path-1="docs"
+ * - path-2="api"
+ * 
+ * This allows for targeted styling of links based on their destination.
+ */
+
+/**
+ * Regular expression to extract domains and path segments from URLs
+ * 
+ * This regex has two capture groups:
+ * - Group 1: Domain from http(s):// URLs (e.g., "example.com" from "https://example.com/path")
+ * - Group 2: Path segments from relative URLs (e.g., "docs" from "/docs/page")
+ * 
+ * The 'g' flag enables global matching to find all segments in a URL.
+ */
+const pathSegmentRegex = /(?:http[s]*:\/\/([^\/]*)|(?:\/([^\/?]*)))/g;
+
+/**
+ * Applies link enhancements to a markdown-it instance
+ * 
+ * @param {Object} md - The markdown-it instance to enhance
+ * 
+ * This function overrides the default link_open and link_close renderers
+ * to add path-based attributes and special handling for auto-detected links.
+ */
+function applyLinkEnhancements(md) {
+  
+  /**
+   * Custom link_open renderer that adds path attributes
+   * 
+   * @param {Array} tokens - Array of all tokens being processed
+   * @param {Number} idx - Index of the current link_open token
+   * @param {Object} options - Markdown-it options
+   * @param {Object} env - Environment/context object
+   * @param {Object} renderer - The renderer instance
+   * @returns {String} HTML string for the opening anchor tag with path attributes
+   */
+  md.renderer.rules.link_open = function (tokens, idx, options, env, renderer) {
+    let token = tokens[idx];
+    
+    // Process all attributes of the link token
+    let attrs = token.attrs.reduce((str, attr) => {
+      let name = attr[0];   // Attribute name (e.g., 'href', 'title')
+      let value = attr[1];  // Attribute value (e.g., 'https://example.com')
+      
+      // Special processing for href attributes to add path information
+      if (name === 'href') {
+        let index = 0;
+        
+        // Extract domain and path segments using the regex
+        value.replace(pathSegmentRegex, (match, domain, pathSegment) => {
+          // Add path-N attributes for each segment found
+          // domain OR pathSegment will be defined (not both, due to regex groups)
+          str += `path-${index++}="${domain || pathSegment}" `;
+        });
+      }
+      
+      // Add the original attribute to the string
+      str += `${name}="${value}" `;
+      return str;
+    }, '');
+
+    // Create the opening anchor tag with all attributes
+    let anchor = `<a ${attrs}>`;
+    
+    // Special handling for auto-detected links (linkify plugin)
+    // These get an extra <span> wrapper for styling purposes
+    return token.markup === 'linkify' ? anchor + '<span>' : anchor;
+  };
+
+  /**
+   * Custom link_close renderer
+   * 
+   * @param {Array} tokens - Array of all tokens being processed
+   * @param {Number} idx - Index of the current link_close token
+   * @param {Object} options - Markdown-it options
+   * @param {Object} env - Environment/context object
+   * @param {Object} renderer - The renderer instance
+   * @returns {String} HTML string for the closing anchor tag
+   */
+  md.renderer.rules.link_close = function (tokens, idx, options, env, renderer) {
+    // Close the extra span for linkify links, or just close the anchor
+    return tokens[idx].markup === 'linkify' ? '</span></a>' : '</a>';
+  };
+}
+
+module.exports = applyLinkEnhancements;

package/src/markdown-it/plugins.js

@@ -0,0 +1,118 @@
+/**
+ * Configures and applies external markdown-it plugins to a given markdown-it instance.
+ * This module centralizes plugin loading to reduce complexity in the main index.js file.
+ * It handles only the external npm plugins (e.g., markdown-it-attrs), not custom extensions.
+ * 
+ * @param {Object} md - The markdown-it instance to configure
+ * @param {Object} config - Configuration object (e.g., for TOC anchor symbol)
+ * @param {Object} containers - The markdown-it-container instance (passed to avoid re-requiring)
+ * @param {Object} noticeTypes - Object defining valid notice types (e.g., { note: 1, issue: 1, ... })
+ * @param {Object} noticeTitles - Object to track notice titles (passed to maintain state)
+ * @returns {Object} The configured markdown-it instance
+ */
+function configurePlugins(md, config, containers, noticeTypes, noticeTitles, setToc) {
+  // Apply attribute support for elements (e.g., {.class} syntax)
+  // This enables adding CSS classes or IDs to markdown elements without HTML.
+  md.use(require('markdown-it-attrs'));
+
+  // Enable chart rendering from code blocks (e.g., ```chart ... ```)
+  // Useful for embedding diagrams directly in markdown.
+  md.use(require('markdown-it-chart').default);
+
+  // Support definition lists (e.g., term\n: definition)
+  // Enhances standard markdown with formal definition formatting.
+  md.use(require('markdown-it-deflist'));
+
+  // Add reference-style links and footnotes
+  // Allows cleaner link management in long documents.
+  md.use(require('markdown-it-references'));
+
+  // Enable Font Awesome icons (e.g., :fa-icon:)
+  // Integrates icon rendering for visual enhancements.
+  md.use(require('markdown-it-icons').default, 'font-awesome');
+
+  // Support <ins> tags for inserted text (e.g., ++text++)
+  // Useful for highlighting additions in specs.
+  md.use(require('markdown-it-ins'));
+
+  // Support <mark> tags for highlighted text (e.g., ==text==)
+  // Helps emphasize important terms or sections.
+  md.use(require('markdown-it-mark'));
+
+  // Enable textual UML diagrams (e.g., @startuml ... @enduml)
+  // Allows embedding diagrams without external tools.
+  md.use(require('markdown-it-textual-uml'));
+
+  // Support subscript text (e.g., H~2~O)
+  // Essential for scientific or technical writing.
+  md.use(require('markdown-it-sub'));
+
+  // Support superscript text (e.g., E=mc^2^)
+  // Complements subscript for mathematical expressions.
+  md.use(require('markdown-it-sup'));
+
+  // Enable task lists (e.g., - [x] Task)
+  // Great for checklists in documentation.
+  md.use(require('markdown-it-task-lists'));
+
+  // Support multi-line tables with rowspan/colspan
+  // Extends basic tables for complex layouts.
+  md.use(require('markdown-it-multimd-table'), {
+    multiline: true,
+    rowspan: true,
+    headerless: true
+  });
+
+  // Configure notice containers (e.g., ::: note ... :::)
+  // Uses the passed containers plugin for custom blocks like warnings or examples.
+  md.use(containers, 'notice', {
+    validate: function (params) {
+      // Check if the notice type is valid (e.g., 'note', 'issue')
+      let matches = params.match(/(\w+)\s?(.*)?/);
+      return matches && noticeTypes[matches[1]];
+    },
+    render: function (tokens, idx) {
+      // Render opening or closing tags for notices
+      let matches = tokens[idx].info.match(/(\w+)\s?(.*)?/);
+      if (matches && tokens[idx].nesting === 1) {
+        let id;
+        let type = matches[1];
+        if (matches[2]) {
+          // Custom ID from title
+          id = matches[2].trim().replace(/\s+/g, '-').toLowerCase();
+          if (noticeTitles[id]) id += '-' + noticeTitles[id]++;
+          else noticeTitles[id] = 1;
+        } else {
+          // Auto-generated ID
+          id = type + '-' + noticeTypes[type]++;
+        }
+        return `<div id="${id}" class="notice ${type}"><a class="notice-link" href="#${id}">${type.toUpperCase()}</a>`;
+      } else {
+        return '</div>\n';
+      }
+    }
+  });
+
+  // Add syntax highlighting with Prism.js
+  // Enhances code blocks with colorized syntax.
+  md.use(require('markdown-it-prism'));
+
+  // Generate table of contents with anchors
+  // Automatically creates TOC from headings, with customizable symbols.
+  md.use(require('markdown-it-toc-and-anchor').default, {
+    tocClassName: 'toc',
+    tocFirstLevel: 2,
+    tocLastLevel: 4,
+    tocCallback: (_md, _tokens, html) => setToc(html),
+    anchorLinkSymbol: config.specs[0].anchor_symbol || '§',
+    anchorClassName: 'toc-anchor d-print-none'
+  });
+
+  // Enable KaTeX for math rendering (e.g., $$...$$)
+  // Supports inline and block math expressions.
+  md.use(require('@traptitech/markdown-it-katex'));
+
+  return md;
+}
+
+module.exports = { configurePlugins };

package/src/markdown-it/table-enhancement.js

@@ -0,0 +1,97 @@
+'use strict';
+
+/**
+ * Markdown-it Table Enhancement Module
+ * 
+ * This module enhances the default table rendering by:
+ * 1. Adding Bootstrap CSS classes for styling (table, table-striped, table-bordered, table-hover)
+ * 2. Wrapping tables in a responsive container div for mobile-friendly display
+ * 
+ * The markdown-it library uses a token-based rendering system where:
+ * - Tokens represent different parts of the markdown (table_open, table_close, etc.)
+ * - Renderer rules are functions that convert tokens to HTML
+ * - We override the default rules to add our custom behavior
+ */
+
+/**
+ * Applies table enhancements to a markdown-it instance
+ * 
+ * @param {Object} md - The markdown-it instance to enhance
+ * 
+ * How this works:
+ * - Saves the original table_open and table_close renderers as fallbacks
+ * - Overrides them with custom functions that add Bootstrap classes and responsive wrapper
+ * - The table_open rule adds classes to the <table> element and opens a wrapper <div>
+ * - The table_close rule closes both the </table> and the wrapper </div>
+ */
+function applyTableEnhancements(md) {
+  // Store the original table renderers so we can call them after our modifications
+  // If no custom renderer exists, markdown-it provides a default self.renderToken function
+  const originalTableRender = md.renderer.rules.table_open || function (tokens, idx, options, env, self) {
+    return self.renderToken(tokens, idx, options);
+  };
+
+  const originalTableCloseRender = md.renderer.rules.table_close || function (tokens, idx, options, env, self) {
+    return self.renderToken(tokens, idx, options);
+  };
+
+  /**
+   * Custom table_open renderer
+   * 
+   * @param {Array} tokens - Array of all tokens being processed
+   * @param {Number} idx - Index of the current table_open token
+   * @param {Object} options - Markdown-it options
+   * @param {Object} env - Environment/context object
+   * @param {Object} self - The renderer instance
+   * @returns {String} HTML string for the opening table with wrapper
+   */
+  md.renderer.rules.table_open = function (tokens, idx, options, env, self) {
+    // Get the current table token to modify its attributes
+    const token = tokens[idx];
+    
+    // Find if the table already has a class attribute
+    const classIndex = token.attrIndex('class');
+    
+    // Define the Bootstrap classes we want to add
+    const tableClasses = 'table table-striped table-bordered table-hover';
+
+    if (classIndex < 0) {
+      // No existing class attribute - add our classes
+      token.attrPush(['class', tableClasses]);
+    } else {
+      // Class attribute exists - append our classes if they're not already present
+      const existingClasses = token.attrs[classIndex][1];
+      
+      // Filter out classes that are already present to avoid duplicates
+      const classesToAdd = tableClasses
+        .split(' ')
+        .filter(cls => !existingClasses.includes(cls))
+        .join(' ');
+
+      // Only append if we have new classes to add
+      if (classesToAdd) {
+        token.attrs[classIndex][1] = existingClasses + ' ' + classesToAdd;
+      }
+    }
+
+    // Return the responsive wrapper div + the enhanced table opening tag
+    return '<div class="table-responsive-md">' + originalTableRender(tokens, idx, options, env, self);
+  };
+
+  /**
+   * Custom table_close renderer
+   * 
+   * @param {Array} tokens - Array of all tokens being processed
+   * @param {Number} idx - Index of the current table_close token
+   * @param {Object} options - Markdown-it options
+   * @param {Object} env - Environment/context object
+   * @param {Object} self - The renderer instance
+   * @returns {String} HTML string for closing the table and wrapper
+   */
+  md.renderer.rules.table_close = function (tokens, idx, options, env, self) {
+    // Close both the table and the responsive wrapper div
+    return originalTableCloseRender(tokens, idx, options, env, self) + '</div>';
+  };
+}
+
+module.exports = applyTableEnhancements;

package/src/markdown-it/template-tag-syntax.js

@@ -0,0 +1,152 @@
+'use strict';
+
+const { ESCAPED_PLACEHOLDER } = require('../pipeline/preprocessing/escape-processor.js');
+
+/**
+ * Markdown-it Template-Tag Syntax Module
+ * 
+ * This module adds support for custom template-tag syntax like [[ref:spec,term]] in markdown.
+ * It handles the parsing and rendering of these special constructs.
+ * 
+ * Template-tag syntax format: [[type:arg1,arg2,arg3]]
+ * Examples:
+ * - [[def:term,alias]] - Define a term with an alias
+ * - [[tref:external-spec,term]] - Reference a term from external specification
+ * - [[xref:spec,term]] - Cross-reference to another specification
+ * 
+ * The module works in two phases:
+ * 1. PARSING: Scans markdown text for [[...]] patterns and creates template-tag tokens
+ * 2. RENDERING: Converts template-tag tokens to final HTML using template-tag handlers
+ */
+
+/**
+ * Configuration constants for template-tag syntax
+ * These define the delimiters and parsing rules for template-tag markers
+ */
+const { templateTags } = require('../utils/regex-patterns');
+
+const levels = 2;                         // Number of bracket characters (e.g., 2 = [[]])
+const openString = '['.repeat(levels);    // Opening delimiter: '[['
+const closeString = ']'.repeat(levels);   // Closing delimiter: ']]'
+
+// Regular expression to extract template-tag components from [[type:args]] syntax
+// Group 1: template-tag type (e.g., 'ref', 'tref', 'def')
+// Group 2: arguments (everything after the colon, comma-separated)
+const contentRegex = templateTags.content;
+
+/**
+ * Applies template-tag syntax support to a markdown-it instance
+ * 
+ * @param {Object} md - The markdown-it instance to enhance
+ * @param {Array} templates - Array of template-tag handler objects
+ * 
+ * Each template-tag handler should have:
+ * - filter(type): function that returns true if this handler processes the given type
+ * - parse(token, type, ...args): optional preprocessing function
+ * - render(token, type, ...args): function that returns HTML string
+ */
+function applyTemplateTagSyntax(md, templates = []) {
+  
+  /**
+   * Custom inline parsing rule for template-tag syntax
+   * 
+   * This rule is added to markdown-it's inline ruler (which processes inline elements)
+   * and runs after the 'emphasis' rule to handle our [[template-tag]] syntax.
+   * 
+   * @param {Object} state - Parser state object containing source text and position
+   * @param {Boolean} silent - If true, don't modify state (used for validation)
+   * @returns {Boolean} true if template-tag was found and processed, false otherwise
+   */
+  function templates_ruler(state, silent) {
+    // Get current position in the source text
+    var start = state.pos;
+
+    // Skip processing if we're at an escaped placeholder (handled by escape mechanism)
+    if (state.src.slice(start, start + ESCAPED_PLACEHOLDER.length) === ESCAPED_PLACEHOLDER) {
+      return false;
+    }
+
+    // Check if we're at the start of a template-tag marker [[
+    let prefix = state.src.slice(start, start + levels);
+    if (prefix !== openString) {
+      return false; // Not a template-tag, let other rules handle it
+    }
+    
+    // Find the matching closing marker ]]
+    var indexOfClosingBrace = state.src.indexOf(closeString, start);
+    
+    if (indexOfClosingBrace > 0) {
+      // Extract the content between [[ and ]]
+      let templateTagContent = state.src.slice(start + levels, indexOfClosingBrace);
+      
+      // Parse the template-tag content using regex
+      let match = contentRegex.exec(templateTagContent);
+      if (!match) {
+        return false; // Invalid template-tag syntax
+      }
+
+      // Extract template-tag type and arguments
+      let type = match[1];
+      let template = templates.find(t => t.filter(type) && t);
+      
+      if (!template) {
+        return false; // No handler found for this template-tag type
+      }
+
+      // Parse arguments (comma-separated list)
+      let args = match[2] ? match[2].trim().split(/\s*,+\s*/) : [];
+      
+      // Create a new template-tag token in the token stream
+      // This token will be processed later during rendering
+      let token = state.push('template', '', 0);
+      token.content = match[0]; // Store original matched content
+      token.info = { type, template, args }; // Store parsed information
+
+      // If the template-tag has a parse function, call it for preprocessing
+      // This allows template-tags to modify their content during parsing
+      if (template.parse) {
+        token.content = template.parse(token, type, ...args) || token.content;
+      }
+
+      // Move parser position past the template-tag
+      state.pos = indexOfClosingBrace + levels;
+      return true; // Template-tag successfully processed
+    }
+
+    return false; // No closing marker found
+  }
+
+  // Register the template-tag parsing rule with markdown-it
+  // It runs after 'emphasis' to ensure proper precedence
+  md.inline.ruler.after('emphasis', 'templates', templates_ruler);
+
+  /**
+   * Renderer for template-tag tokens
+   * 
+   * This function is called during the rendering phase to convert
+   * template-tag tokens into their final HTML representation.
+   * 
+   * @param {Array} tokens - Array of all tokens being rendered
+   * @param {Number} idx - Index of current template-tag token
+   * @param {Object} options - Markdown-it options
+   * @param {Object} env - Environment/context object
+   * @param {Object} renderer - The renderer instance
+   * @returns {String} HTML string for this template-tag
+   */
+  md.renderer.rules.template = function (tokens, idx, options, env, renderer) {
+    let token = tokens[idx];
+    let template = token.info.template;
+    
+    // Call the template-tag's render function if it exists
+    if (template.render) {
+      let result = template.render(token, token.info.type, ...token.info.args);
+      // Return the rendered result, or fall back to original syntax if render fails
+      return result || (openString + token.content + closeString);
+    }
+    
+    // No render function - return the content as-is
+    return token.content;
+  };
+}
+
+module.exports = applyTemplateTagSyntax;

package/src/parsers/index.js

@@ -0,0 +1,16 @@
+/**
+ * Parsers Module Index - Functional Style
+ * 
+ * This module provides a centralized export point for all parser functions.
+ * It promotes clean imports and consistent API access across the codebase.
+ * The functional approach provides better tree-shaking and simpler testing.
+ */
+
+const templateTagParser = require('./template-tag-parser');
+const specParser = require('./spec-parser');
+
+module.exports = {
+  // Parser factory functions
+  createTemplateTagParser: templateTagParser.createTemplateTagParser,
+  createSpecParser: specParser.createSpecParser
+};

package/src/parsers/spec-parser.js

@@ -0,0 +1,152 @@
+  /**
+ * Specification Parser - Functional Style
+ * 
+ * This module provides pure functions for processing specification-related markdown extensions:
+ * - [[spec: name]] - Individual specification references
+ * - [[spec-*: name]] - Grouped specification references (e.g., spec-normative, spec-informative)
+ * 
+ * The functional approach isolates specification logic from terminology concerns,
+ * reducing cognitive complexity and improving maintainability through pure functions.
+ */
+
+const { renderRefGroup } = require('../pipeline/rendering/render-utils.js');
+const { whitespace } = require('../utils/regex-patterns');
+
+/**
+ * Normalizes a specification name for consistent lookup
+ * @param {string} name - The original specification name
+ * @returns {string} The normalized name (uppercase with hyphens)
+ */
+function normalizeSpecName(name) {
+  return name.replace(whitespace.oneOrMore, '-').toUpperCase();
+}
+
+/**
+ * Looks up a specification in the corpus using various name formats
+ * @param {Object} specCorpus - The specification corpus
+ * @param {string} name - The specification name to look up
+ * @returns {Object|null} The found specification or null
+ */
+function findSpecInCorpus(specCorpus, name) {
+  const normalizedName = normalizeSpecName(name);
+  
+  return specCorpus[normalizedName] ||
+    specCorpus[normalizedName.toLowerCase()] ||
+    specCorpus[name.toLowerCase()] ||
+    specCorpus[name] ||
+    null;
+}
+
+/**
+ * Processes specification reference tokens during parsing phase
+ * Looks up specification details and stores them for later rendering
+ * @param {Object} specCorpus - The loaded specification corpus
+ * @param {Object} globalState - Global state object containing specGroups
+ * @param {Object} token - The markdown-it token being processed
+ * @param {string} type - The type of spec construct (e.g., 'spec', 'spec-normative')
+ * @param {string} name - The specification name to look up
+ */
+function parseSpecReference(specCorpus, globalState, token, type, name) {
+  if (!name) return;
+
+  const spec = findSpecInCorpus(specCorpus, name);
+
+  if (spec) {
+    // Store the normalized name for consistent referencing
+    const normalizedName = normalizeSpecName(name);
+    spec._name = normalizedName;
+
+    // Organize specifications by type/group for rendering
+    const group = globalState.specGroups[type] = globalState.specGroups[type] || {};
+    token.info.spec = group[normalizedName] = spec;
+  }
+}
+
+/**
+ * Renders an individual specification reference as a link
+ * @param {Object} token - The token containing spec information
+ * @returns {string} HTML anchor element linking to the specification
+ */
+function renderIndividualSpec(token) {
+  const spec = token.info.spec;
+  if (!spec) return '';
+
+  // Create a reference link to the specification
+  // The href uses a 'ref:' prefix to distinguish from term references
+  return `[<a class="spec-reference" href="#ref:${spec._name}">${spec._name}</a>]`;
+}
+
+/**
+ * Renders a group of specifications as a formatted list
+ * @param {string} type - The specification group type
+ * @param {Object} specGroups - The global specGroups object
+ * @returns {string} HTML representation of the specification group
+ */
+function renderSpecGroup(type, specGroups) {
+  // Delegate to the render utility which handles the complex group formatting
+  return renderRefGroup(type, specGroups);
+}
+
+/**
+ * Renders specification references during the rendering phase
+ * Creates either individual spec links or grouped spec lists
+ * @param {Object} specGroups - The global specGroups object
+ * @param {Object} token - The markdown-it token being rendered
+ * @param {string} type - The type of spec construct
+ * @param {string} name - The specification name (if individual reference)
+ * @returns {string} HTML for the specification reference or group
+ */
+function renderSpecReference(specGroups, token, type, name) {
+  if (name) {
+    // Render individual specification reference
+    return renderIndividualSpec(token);
+  } else {
+    // Render grouped specification references (when no specific name is provided)
+    return renderSpecGroup(type, specGroups);
+  }
+}
+
+/**
+ * Gets all specifications in a specific group
+ * Utility function for accessing grouped specifications
+ * @param {Object} specGroups - The global specGroups object
+ * @param {string} type - The specification group type
+ * @returns {Object} Object containing all specs in the group
+ */
+function getSpecGroup(specGroups, type) {
+  return specGroups[type] || {};
+}
+
+/**
+ * Checks if a specification exists in the corpus
+ * @param {Object} specCorpus - The specification corpus
+ * @param {string} name - The specification name to check
+ * @returns {boolean} True if the specification exists
+ */
+function hasSpec(specCorpus, name) {
+  return findSpecInCorpus(specCorpus, name) !== null;
+}
+
+/**
+ * Creates a specification parser function with bound corpus and global state.
+ * This provides a clean interface similar to the class-based approach but with functional benefits.
+ * @param {Object} specCorpus - The specification corpus
+ * @param {Object} globalState - Global state object
+ * @returns {Object} An object with parser and renderer functions
+ */
+function createSpecParser(specCorpus, globalState) {
+  return {
+    parseSpecReference: (token, type, name) => parseSpecReference(specCorpus, globalState, token, type, name),
+    renderSpecReference: (token, type, name) => renderSpecReference(globalState.specGroups, token, type, name),
+    hasSpec: (name) => hasSpec(specCorpus, name),
+    getSpecGroup: (type) => getSpecGroup(globalState.specGroups, type)
+  };
+}
+
+module.exports = {
+  createSpecParser,
+  // Export individual functions for testing purposes  
+  parseSpecReference,
+  renderIndividualSpec,
+  hasSpec
+};