Package sk.iway.iwcm.rag.service

Class MarkdownSourceService

java.lang.Object
sk.iway.iwcm.rag.service.MarkdownSourceService
@Service public class MarkdownSourceService extends Object
Resolves explicitly configured documentation roots in the web application or local filesystem.

  • Constructor Details

    • MarkdownSourceService

      public MarkdownSourceService()

  • Method Details

    • getRoots

      public List<String> getRoots()
      Reads and normalizes the globally configured documentation roots.
      Returns:
      distinct roots in configuration order, or an empty list when none are configured

    • requireRoot

      public String requireRoot(String folder)
      Returns a normalized root only when it exactly matches the configured allowlist.
      Parameters:
      folder - requested documentation root
      Returns:
      normalized configured root
      Throws:
      IllegalArgumentException - if the root is missing, invalid, or not configured

    • getRelativePath

      public String getRelativePath(String configuredRoot, String fullPath)
      Returns an indexable path below a normalized configured root without requiring the source to exist.
      Parameters:
      configuredRoot - normalized configured root
      fullPath - full logical source path
      Returns:
      eligible root-relative path, or null when outside the root or ineligible

    • resolveRoot

      public Path resolveRoot(String folder) throws IOException
      Resolves an existing directory, confining virtual roots to the deployed web application.
      Parameters:
      folder - configured virtual or filesystem documentation root
      Returns:
      canonical directory path
      Throws:
      IOException - if the root cannot be resolved to an allowed existing directory

    • getFiles

      public List<String> getFiles(String folder) throws IOException
      Lists eligible language-classified Markdown files recursively without following symbolic links.
      Parameters:
      folder - configured documentation root
      Returns:
      sorted root-relative source paths
      Throws:
      IOException - if the root or its files cannot be scanned

    • getFiles

      public List<String> getFiles(String folder, String selectedDirectory, boolean includeSubfolders) throws IOException
      Lists selected eligible files while retaining paths relative to the configured root.
      Parameters:
      folder - configured documentation root
      selectedDirectory - root-relative directory, empty or null for the root
      includeSubfolders - whether to scan descendant directories
      Returns:
      sorted root-relative source paths
      Throws:
      IOException - if the selected directory or its files cannot be scanned

    • getDirectories

      public List<MarkdownSourceService.DirectoryNode> getDirectories(String folder, String selectedDirectory) throws IOException
      Lists immediate eligible child directories for lazy loading in the folder selector.
      Parameters:
      folder - configured documentation root
      selectedDirectory - root-relative directory, empty or null for the root
      Returns:
      child nodes sorted by name, excluding symbolic links and excluded directories
      Throws:
      IOException - if the selected directory or its children cannot be inspected

    • requireDirectory

      public String requireDirectory(String directory)
      Validates a root-relative directory without requiring it to exist, allowing removal of deleted sources.
      Parameters:
      directory - root-relative directory, empty or null for the root
      Returns:
      validated directory, or an empty string for the root
      Throws:
      IllegalArgumentException - if the relative path is invalid or includes excluded segments

    • isInDirectory

      public boolean isInDirectory(String sourcePath, String directory, boolean includeSubfolders)
      Matches a root-relative source against a selected directory without touching the filesystem.
      Parameters:
      sourcePath - root-relative source path
      directory - selected root-relative directory
      includeSubfolders - whether descendants also match
      Returns:
      true when the source is indexable and lies in the selected scope

    • resolveFile

      public Path resolveFile(String folder, String sourcePath) throws IOException
      Revalidates a queued source path and rejects symlinks, including links in intermediate directories.
      Parameters:
      folder - configured documentation root
      sourcePath - root-relative Markdown path
      Returns:
      resolved path, which may refer to a deleted source
      Throws:
      IOException - if the root is unavailable, a path contains a symlink, or confinement fails

    • isFileSystemRoot

      public boolean isFileSystemRoot(String root)
      Distinguishes explicit filesystem roots from application-relative paths without checking disk state.
      Parameters:
      root - logical root, possibly null
      Returns:
      true when the root starts with file:

    • isExcludedDirectory

      public boolean isExcludedDirectory(String name)

    • getLanguages

      public List<String> getLanguages()
      Returns normalized shared language codes, including the standard documentation folder languages.
      Returns:
      configured language codes plus sk, en, and cs, without duplicates

    • detectLanguage

      public String detectLanguage(String root, String sourcePath)
      Finds the nearest supported language directory in the configured root and root-relative source path.
      Parameters:
      root - documentation root
      sourcePath - root-relative Markdown path
      Returns:
      nearest recognized language code, or null for an ineligible or unclassified source

    • requireLanguage

      public String requireLanguage(String language)
      Validates and normalizes a documentation language used for retrieval or chunk metadata.
      Parameters:
      language - language code with an optional regional suffix
      Returns:
      trimmed lowercase language code
      Throws:
      IllegalArgumentException - if the language code is missing or has invalid syntax

    • isIndexable

      public boolean isIndexable(String sourcePath)

    • getUrl

      public String getUrl(String root, String sourcePath)
      Builds a Docsify hash URL, or returns null for filesystem roots without a public web address.
      Parameters:
      root - documentation root
      sourcePath - indexable root-relative Markdown path
      Returns:
      encoded context-relative viewer URL, or null for filesystem roots