repo-sage Documentation

PIPELINE

Utilities (118 functions)

stripCodeFences

Remove Markdown-style triple-backtick code fences and surrounding whitespace from a text block.

all-utils.js

isIgnoredDirName

Determine whether a directory name should be skipped based on a built-in ignore list.

all-utils.js

shouldIgnore

Determine whether a full path should be ignored based on configured substring matches.

all-utils.js

isCodeFile

Heuristically decide whether a path represents a source code file based on extension.

all-utils.js

walkDir

Recursively walk a directory tree starting at startPath and return a list of code file paths.

all-utils.js

detectLanguage

Map a file extension from a file path to a short string identifier representing

all-utils.js

chatCompletion

Simple chat completion wrapper that calls the OpenAI Chat Completions endpoint and returns

all-utils.js

chatJSON

Chat completion wrapper that expects the assistant to return STRICT JSON. Calls chatCompletion,

all-utils.js

guessHttpMethod

Heuristically infer an HTTP method (GET/POST/PUT/DELETE) from a URL or endpoint name.

all-utils.js

ensureDirs

Ensure that one or more directory paths exist by creating them recursively.

all-utils.js

normalizePath

Normalize Windows backslashes to forward slashes for normalized, portable path strings.

all-utils.js

analyzeRepository

Asynchronously scans a repository path to build a static analysis report describing

analyze-repo.js

classifyFile

Infers the architectural classification of a file based on its path and filename patterns.

analyze-repo.js

checkForViolations

Scans file content line-by-line for known anti-patterns and architecture violations.

analyze-repo.js

extractMethods

Parses content to extract function and method names for JavaScript/TypeScript and Dart files.

analyze-repo.js

extractImports

Extracts module import specifiers from JS/TS or Dart file content using regex patterns.

analyze-repo.js

extractClassName

Attempts to extract the first declared class name from JavaScript/TypeScript content.

analyze-repo.js

extractFlutterDeps

Parses a pubspec.yaml string to collect dependency package names listed under `dependencies:`.

analyze-repo.js

generateSummary

Aggregates analysis results into a concise summary object including counts of files,

analyze-repo.js

getViolationsByType

Aggregates a list of violations by their `type` field and sorts descending by count.

analyze-repo.js

getTopViolators

Identifies the top files by number of violations, returning up to the top 10.

analyze-repo.js

classifyByContent

Inspect a source file's content and path to heuristically classify the file's likely role within a codebase.

classify.js

detectPatterns

Mutates a supplied "patterns" summary object by detecting frameworks and common cross-cutting features

classify.js

buildContext

Build a summarized context object from an analysis result. Aggregates basic stats,

context.js

enhanceViolations

Enhance a list of lint/analysis violations with contextual suggestions based on detected patterns.

context.js

buildApiCatalogAndDocs

Build an API catalog and service documentation from a comprehensive analysis object.

context.js

describeServicePurpose

Infer a human-friendly purpose description for a service based on its name and classification.

context.js

parseDocblock

" or "/*" and trailing "

docblock-parser.js

stripCodeFences

Remove surrounding Markdown code fences (```lang ... ```) and trim whitespace.

engine.js

isIgnoredDirName

Check whether a single directory name should be ignored (exact match against IGNORED_DIRS).

engine.js

shouldIgnore

Determine whether a full path should be ignored based on substrings in IGNORE_PATH_PARTS.

engine.js

isCodeFile

Determine if a file path corresponds to a source code file based on extension whitelist.

engine.js

walkDir

Recursively walk a directory tree starting at startPath and collect code file paths.

engine.js

detectLanguage

Map a file extension to a language/runtime identifier used by downstream tooling.

engine.js

chatCompletion

Simple async wrapper around OpenAI chat completions that returns plain text.

engine.js

chatJSON

Wrapper around chatCompletion that expects the model response to be STRICT JSON.

engine.js

listFiles

Recursively scan a directory and return a flat list of JavaScript (.js) file paths,

extract-docblocks.js

extractDocblocks

Extract block-style JSDoc comment blocks (/** ... *\/) from a source string.

extract-docblocks.js

detectFunctionName

Heuristically detect the JavaScript function or identifier name that immediately

extract-docblocks.js

processFile

Read a JavaScript file, extract docblocks, parse each docblock with the imported

extract-docblocks.js

printViolationsSummary

Produce a human-readable summary of the violations grouped by severity and print to stdout.

extract-violations.js

extractClasses

Parse source file content and extract top-level class/struct names for supported languages.

extract.js

extractFunctions

Analyze source content and return a list of top-level functions and methods with metadata.

extract.js

within

Return a short slice of content starting at startIndex for heuristic analysis.

extract.js

extractImports

Extract import/module dependency specifiers from source content for JS/TS/Go/Dart.

extract.js

extractEndpoints

Heuristically extract network endpoints (URLs and route definitions) from source content.

extract.js

extractLanguageSpecific

Extract language-specific artifacts from a file: Go structs, Node models/routes, Flutter/Dart classes and fields.

extract.js

extractGo

Parse Go source content to extract package name, struct type definitions and HTTP handler functions.

extract.js

extractNode

Parse Node/JS/TS content to find Mongoose-like schema blocks, models, express routes and middleware.

extract.js

extractSchemaFields

Parse a snippet that represents a schema object and extract field name/type pairs.

extract.js

isIgnoredDirName

Check whether a directory entry name should be ignored based on the IGNORED_DIRS set.

generate-comments.js

shouldIgnore

Determine whether a full filesystem path should be skipped based on IGNORE_PATH_PARTS.

generate-comments.js

isCodeFile

Quick heuristic to determine whether a given path refers to a source code file

generate-comments.js

stripCodeFences

Remove leading/trailing Markdown code-fences (```...```) from a string and trim whitespace.

generate-comments.js

walkDir

Recursively walk a starting directory and collect all files that are considered code files.

generate-comments.js

detectLanguage

Map file extensions to a short language key used to select prompts and parsing behavior.

generate-comments.js

getDocSystemPrompt

Return a language-specific system prompt for the documentation generation model.

generate-comments.js

getMetaSystemPrompt

Produce the system prompt used to instruct the model to extract structured metadata

generate-comments.js

generateDocForFile

Use the OpenAI Chat Completions API to request insertion of doc-blocks into a source file.

generate-comments.js

extractMetadataForFile

Use the OpenAI Chat Completions API to extract structured metadata (api endpoints and models)

generate-comments.js

escapeHtml

generate-doc-html.js

generateCSS

generate-doc-html.js

generateNav

generate-doc-html.js

generateServers

generate-doc-html.js

generateMounts

generate-doc-html.js

generateRoutes

generate-doc-html.js

generateModels

generate-doc-html.js

generateAPIs

generate-doc-html.js

generateFunctions

generate-doc-html.js

generateMiddleware

generate-doc-html.js

generateDatabases

generate-doc-html.js

generateClusters

generate-doc-html.js

generateSockets

generate-doc-html.js

generateHTML

generate-doc-html.js

hasDocumentation

Analyze a source file string and determine whether it already

generate-docs.js

count

Safely counts elements in an array-like value.

generate-report.js

diffList

Produce and print lists of added/removed items between two nodeStructure lists keyed by `key` (e.g., routes, models, servers).

generate-report.js

addApiToCatalog

Add a deduplicated API entry to an in-memory catalog keyed by "METHOD url". Tracks which service used the API.

generate-report.js

escapeHtml

Escape characters in a string for safe insertion into HTML content to prevent markup injection.

generate-report.js

anchorId

Generate a safe anchor/id string by combining a prefix and a sanitized name. Removes non-alphanumeric characters from name.

generate-report.js

navBar

Render a small HTML navigation bar used across generated report pages.

generate-report.js

baseCss

Returns the base CSS stylesheet used by all generated HTML pages.

generate-report.js

baseJs

Returns a small JS snippet used across the generated HTML pages for toggling sections and initial UI state.

generate-report.js

pageTemplate

Compose a full HTML page using provided title/header/body and optionally include high-level analysis stats.

generate-report.js

renderServicesSection

Render a collapsible HTML section listing available services with links to their documentation blocks.

generate-report.js

renderApiCatalogSection

Render an API catalog grouped by domain/origin. Each endpoint contains method, url, and list of services that use it.

generate-report.js

renderServiceDocs

Render detailed service and API documentation sections from documentation data. Supports methods, params, returns and endpoints.

generate-report.js

renderModelsStructsBlock

Render a combined Models/Structs/Flutter classes block. Reads model/struct lists from analysis and generates field/index tables.

generate-report.js

renderViolation

Render a single violation object as an HTML block including severity, file path, message, code excerpt and suggestion.

generate-report.js

renderIssuesBySeverity

Render a set of collapsible sections for violations grouped by severity (critical, high, medium, low).

generate-report.js

renderDocumentationSummary

Render a summary section using documentation.json content. Outputs Routes, Servers, Models, Functions, and File Descriptions blocks.

generate-report.js

renderCrossRefsPage

Render cross-reference mappings (route→models, route→collections, model→routes, mount→routes, external APIs) as collapsible sections.

generate-report.js

generateSection

generate-violations-report.js

escapeHtml

generate-violations-report.js

safeList

save-context.js

describeServicePurpose

save-context.js

sanitizeId

Normalize a string to a lowercase dash-separated identifier safe for anchors/ids.

smart-analyze.js

generateId

Generate a stable id string for various entity types used in the documentation structure.

smart-analyze.js

parseParams

Parse an array of parameter doc strings into structured { name, type, description } objects.

smart-analyze.js

parseReturns

Parse return documentation into a structured object with HTTP code, type and description.

smart-analyze.js

parseThrows

Parse thrown errors documentation into structured { code, description } items.

smart-analyze.js

parseSchema

Parse a simple schema definition string into an array of field descriptors.

smart-analyze.js

parseRoute

Parse a route declaration string into method and path. Supports "GET /path" style.

smart-analyze.js

extractServers

Extract server definitions (port, protocol, cluster, workers, database) from docblocks.

smart-analyze.js

extractMounts

Extract Express mount points from docblocks (tag: @mount) and associated router info.

smart-analyze.js

extractRoutes

Extract documented HTTP routes from docblocks (tag: @route) and parse parameters, returns, throws.

smart-analyze.js

extractModels

Extract model/schema declarations from docblocks (tags: @model, @collection, @schema, @indexes).

smart-analyze.js

extractAPIs

Group external API usages (tag: @api) by domain, collect endpoints and usage locations.

smart-analyze.js

extractFunctions

Extract non-route functions from docblocks and infer their type (API Integration, Data Service, etc.).

smart-analyze.js

extractMiddleware

Extract documented middleware entries (tag: @middleware) including purpose and file.

smart-analyze.js

extractDatabases

Group database usage information (tags: @database, @dbname, @host, @authSource, @replicaSet) by dbname.

smart-analyze.js

extractClusters

Aggregate cluster-related docblocks (tag: @cluster) into cluster descriptors with worker counts and files.

smart-analyze.js

extractSockets

Extract socket event documentation (tags: @socket, @emits, @events) into socket descriptors.

smart-analyze.js

extractDomain

Extract the host/domain portion from a URL string. Falls back to the input if not a URL.

smart-analyze.js

inferFunctionType

Heuristically infer a function's role based on docblock tags and file path (API Integration, Data Service, Service Method, Utility).

smart-analyze.js

buildCrossReferences

Enrich the extracted structure with cross-references (anchors) between servers, mounts, routes, models, functions and APIs.

smart-analyze.js

findViolations

violations.js

add

violations.js

FUNCTIONS

stripCodeFences [Utility]

Name:

stripCodeFences

File:

all-utils.js

Type:

Utility

Description:

Remove Markdown-style triple-backtick code fences and surrounding whitespace from a text block.

Parameters

Name	Type	Description
`{string} text - Input text which may contain fenced code block(s).`	any

Returns

Type:

string

Description:

Cleaned text with fences stripped and leading/trailing whitespace removed.

Throws

- Nothing is thrown; falsy input returns an empty string.:

isIgnoredDirName [Utility]

Name:

isIgnoredDirName

File:

all-utils.js

Type:

Utility

Description:

Determine whether a directory name should be skipped based on a built-in ignore list.

Parameters

Name	Type	Description
`{string} name - Single path segment (directory name) to check.`	any

Returns

Type:

boolean

Description:

True if the directory name is in the ignore set, else false.

Throws

- None.:

shouldIgnore [Utility]

Name:

shouldIgnore

File:

all-utils.js

Type:

Utility

Description:

Determine whether a full path should be ignored based on configured substring matches.

Parameters

Name	Type	Description
`{string} fullPath - Full file system path to evaluate.`	any

Returns

Type:

boolean

Description:

True if the path should be ignored, else false.

Throws

- None.:

isCodeFile [Utility]

Name:

isCodeFile

File:

all-utils.js

Type:

Utility

Description:

Heuristically decide whether a path represents a source code file based on extension.

Parameters

Name	Type	Description
`{string} filePath - File path to inspect.`	any

Returns

Type:

boolean

Description:

True if file has a recognized code extension, otherwise false.

Throws

- None.:

walkDir [Utility]

Name:

walkDir

File:

all-utils.js

Type:

Utility

Description:

Recursively walk a directory tree starting at startPath and return a list of code file paths.

Parameters

Name	Type	Description
`{string} startPath - Absolute or relative directory path to begin traversal.`	any

Returns

Type:

string[]

Description:

Array of file paths (strings) that match known code file extensions.

Throws

- Does not throw on typical fs errors; unexpected exceptions may propagate.:

detectLanguage [Utility]

Name:

detectLanguage

File:

all-utils.js

Type:

Utility

Description:

Map a file extension from a file path to a short string identifier representing

Parameters

Name	Type	Description
`{string} filePath - File path used to infer language from its extension.`	any

Returns

Type:

string

Description:

Language key (e.g., "node", "python", "go", "rust", etc.).

Throws

- None.:

chatCompletion [Utility]

Name:

chatCompletion

File:

all-utils.js

Type:

Utility

Description:

Simple chat completion wrapper that calls the OpenAI Chat Completions endpoint and returns

Parameters

Name	Type	Description
`{Object} options`	any
`{string} options.system - System prompt text (role: system). Will be trimmed.`	any
`{string} options.user - User prompt text (role: user). Will be trimmed.`	any
`{number} [options.temperature=1] - Sampling temperature for the completion.`	any
`{string} [options.model=MODEL_NAME] - Model identifier to use for the request.`	any

Returns

Type:

Promise<string>

Description:

Resolves to assistant message content (plain text) with code fences removed.

Throws

{Error} Throws if the OpenAI client errors or the response is malformed (network/HTTP errors).:

chatJSON [Utility]

Name:

chatJSON

File:

all-utils.js

Type:

Utility

Description:

Chat completion wrapper that expects the assistant to return STRICT JSON. Calls chatCompletion,

Parameters

Name	Type	Description
`{Object} options`	any
`{string} options.system - System prompt text (role: system) guiding the model to output JSON.`	any
`{string} options.user - User prompt text (role: user).`	any
`{number} [options.temperature=1] - Model sampling temperature.`	any
`{string} [options.model=MODEL_NAME] - Model identifier.`	any

Returns

Type:

Promise<any>

Description:

Parsed JSON object produced by the assistant.

Throws

{Error} Throws if chatCompletion fails (API/network) or JSON.parse fails. Parse errors include the RAW response in the error message.:

guessHttpMethod [Utility]

Name:

guessHttpMethod

File:

all-utils.js

Type:

Utility

Description:

Heuristically infer an HTTP method (GET/POST/PUT/DELETE) from a URL or endpoint name.

Parameters

Name	Type	Description
`{string} url - The URL or endpoint identifier to analyze.`	any

Returns

Type:

string

Description:

Uppercased HTTP method name ("GET", "POST", "PUT", "DELETE").

Throws

- None.:

ensureDirs [Utility]

Name:

ensureDirs

File:

all-utils.js

Type:

Utility

Description:

Ensure that one or more directory paths exist by creating them recursively.

Parameters

Name	Type	Description
`{...string} dirs - One or more directory paths to create (string varargs).`	any

Returns

Type:

void

Throws

{Error} If fs.mkdirSync fails due to permission issues or invalid paths, the error will propagate.:

normalizePath [Utility]

Name:

normalizePath

File:

all-utils.js

Type:

Utility

Description:

Normalize Windows backslashes to forward slashes for normalized, portable path strings.

Parameters

Name	Type	Description
`{string} p - Input path string to normalize.`	any

Returns

Type:

string

Description:

Path with backslashes replaced by forward slashes.

Throws

- None.:

analyzeRepository [Utility]

Name:

analyzeRepository

File:

analyze-repo.js

Type:

Utility

Description:

Asynchronously scans a repository path to build a static analysis report describing

Parameters

Name	Type	Description
`{string} repoPath - Filesystem path to the repository root to analyze. Defaults to '.' when omitted.`	any

Returns

Type:

Promise<Object>

Description:

analysis - Analysis result object with the following shape:

Throws

{Error} May throw filesystem or JSON parsing errors when reading files (e.g., package.json, pubspec.yaml),:

classifyFile [Utility]

Name:

classifyFile

File:

analyze-repo.js

Type:

Utility

Description:

Infers the architectural classification of a file based on its path and filename patterns.

Parameters

Name	Type	Description
`{string} filePath - Full filesystem path to the file.`	any
`{string} content - File content as a string.`	any

Returns

Type:

{type: string, name: string

Description:

|null} classification - Returns an object with:

checkForViolations [Utility]

Name:

checkForViolations

File:

analyze-repo.js

Type:

Utility

Description:

Scans file content line-by-line for known anti-patterns and architecture violations.

Parameters

Name	Type	Description
`{string} content - File content to scan.`	any
`{string} filePath - Path of the file being scanned (used in returned violation objects).`	any
`{string} ext - File extension (e.g., '.js', '.dart') used to adjust scanning logic if needed.`	any

Returns

Type:

Array<Object>

Description:

violations - Array of violation objects with the shape:

extractMethods [Utility]

Name:

extractMethods

File:

analyze-repo.js

Type:

Utility

Description:

Parses content to extract function and method names for JavaScript/TypeScript and Dart files.

Parameters

Name	Type	Description
`{string} content - File content to analyze.`	any
`{string} ext - File extension ('.js', '.ts', '.dart') to choose parsing heuristics.`	any

Returns

Type:

string[]

Description:

methods - Array of unique method/function names found in the content.

extractImports [Utility]

Name:

extractImports

File:

analyze-repo.js

Type:

Utility

Description:

Extracts module import specifiers from JS/TS or Dart file content using regex patterns.

Parameters

Name	Type	Description
`{string} content - File content to scan.`	any
`{string} ext - File extension ('.js', '.ts', '.dart') to select pattern.`	any

Returns

Type:

string[]

Description:

imports - Array of import source strings found in the file.

extractClassName [Utility]

Name:

extractClassName

File:

analyze-repo.js

Type:

Utility

Description:

Attempts to extract the first declared class name from JavaScript/TypeScript content.

Parameters

Name	Type	Description
`{string} content - File content to search for "class <Name>".`	any

Returns

Type:

string|null

Description:

className - The name of the class if found, otherwise null.

extractFlutterDeps [Utility]

Name:

extractFlutterDeps

File:

analyze-repo.js

Type:

Utility

Description:

Parses a pubspec.yaml string to collect dependency package names listed under `dependencies:`.

Parameters

Name	Type	Description
`{string} yaml - Contents of pubspec.yaml as a string.`	any

Returns

Type:

string[]

Description:

deps - Array of dependency package names defined in the pubspec's dependencies section.

generateSummary [Utility]

Name:

generateSummary

File:

analyze-repo.js

Type:

Utility

Description:

Aggregates analysis results into a concise summary object including counts of files,

Parameters

Name	Type	Description
`{Object} analysis - The full analysis object produced by analyzeRepository.`	any

Returns

Type:

Object

Description:

summary - Summary object with this shape:

getViolationsByType [Utility]

Name:

getViolationsByType

File:

analyze-repo.js

Type:

Utility

Description:

Aggregates a list of violations by their `type` field and sorts descending by count.

Parameters

Name	Type	Description
`{Array<Object>} violations - Array of violation objects as produced by checkForViolations.`	any

Returns

Type:

Array<{type:string, count:number

Description:

>} byType - Sorted array of types with their counts.

getTopViolators [Utility]

Name:

getTopViolators

File:

analyze-repo.js

Type:

Utility

Description:

Identifies the top files by number of violations, returning up to the top 10.

Parameters

Name	Type	Description
`{Array<Object>} violations - Array of violation objects.`	any

Returns

Type:

Array<{file:string, count:number

Description:

>} top - Array sorted by descending violation count, limited to 10 entries.

classifyByContent [Utility]

Name:

classifyByContent

File:

classify.js

Type:

Utility

Description:

Inspect a source file's content and path to heuristically classify the file's likely role within a codebase.

Parameters

Name	Type	Description
	any

Returns

Type:

{ type: string, confidence: number, indicators: string[]

Description:

}

Throws

None - this function is deterministic and does not throw intentionally; may surface exceptions inherited from callers (e.g. if invalid args cause upstream errors).:

detectPatterns [Utility]

Name:

detectPatterns

File:

classify.js

Type:

Utility

Description:

Mutates a supplied "patterns" summary object by detecting frameworks and common cross-cutting features

Parameters

Name	Type	Description
	any

Returns

Type:

void

Description:

- no return value; operation is performed by mutating the passed-in patterns object.

Throws

None - safe heuristic checks; no errors intentionally thrown.:

buildContext [Utility]

Name:

buildContext

File:

context.js

Type:

Utility

Description:

Build a summarized context object from an analysis result. Aggregates basic stats,

Parameters

Name	Type	Description
`{Object} analysis - Analysis result object`	any
`{Object} analysis.stats - Statistics about the codebase (totalFiles, totalLines, byLanguage, entryPoints)`	any
`{Object} analysis.patterns - Detected architecture patterns (frameworks, hasApiService, hasStorageService, hasRepositories, hasHttpCalls, hasSharedPrefs, hasDbQueries)`	any

Returns

Type:

Object

Description:

context - Summarized context

Throws

{TypeError} If analysis or required nested fields are not provided the function may throw when accessing properties:

enhanceViolations [Utility]

Name:

enhanceViolations

File:

context.js

Type:

Utility

Description:

Enhance a list of lint/analysis violations with contextual suggestions based on detected patterns.

Parameters

Name	Type	Description
`{Array<Object>} violations - Array of violation objects detected in the analysis`	any
`{string} violations[].rule - Violation rule identifier (e.g. "hardcoded-url")`	any
`{string} [violations[].suggestion] - Existing suggestion text (optional)`	any
`{Object} context - Context produced by buildContext or equivalent`	any
`{boolean} context.hasApiService - Whether an ApiService exists in the codebase`	any

Returns

Type:

Array<Object>

Description:

- New array of violations (objects from original array may be mutated)

Throws

None expected; will propagate errors if invalid inputs are provided:

buildApiCatalogAndDocs [Utility]

Name:

buildApiCatalogAndDocs

File:

context.js

Type:

Utility

Description:

Build an API catalog and service documentation from a comprehensive analysis object.

Parameters

Name	Type	Description
`{Object} analysis - Full codebase analysis structure`	any
`{Array<Object>} analysis.files - Array of analyzed file objects { path, content, endpoints[], classes[] }`	any
`{Object} analysis.classified - Classified file lists by roles (services, controllers, handlers, routes, repositories, database)`	any
`{Object} [analysis.nodeStructure] - Node-specific structure, may include models: [{ name, file, fields }]`	any
`{Object} [analysis.goStructure] - Go-specific structure, may include structs: [{ name, file, fields }]`	any
`{Array<Object>} [analysis.serviceDocumentation] - Optional array to append node/go model docs before final assignment`	any

Returns

Type:

void

Description:

- Populates analysis.apiCatalog (Array) and analysis.serviceDocumentation (Array)

Throws

{Error} May throw if analysis structure is malformed (e.g. missing arrays expected):

describeServicePurpose [Utility]

Name:

describeServicePurpose

File:

context.js

Type:

Utility

Description:

Infer a human-friendly purpose description for a service based on its name and classification.

Parameters

Name	Type	Description
`{string} name - Name of the service/class/file identifier`	any
`{string} type - Classification string (e.g. "handlers", "controllers", "routes")`	any

Returns

Type:

string

Description:

- Short purpose description (e.g. "Authentication and authorization", "HTTP and remote API calls")

Throws

None:

parseDocblock [Utility]

Name:

parseDocblock

File:

docblock-parser.js

Type:

Utility

Description:

" or "/*" and trailing "

stripCodeFences [Utility]

Name:

stripCodeFences

File:

engine.js

Type:

Utility

Description:

Remove surrounding Markdown code fences (```lang ... ```) and trim whitespace.

Parameters

Name	Type	Description
`{string} text - Input text that may include Markdown code fences.`	any

Returns

Type:

string

Description:

- The trimmed content with code fences removed. Returns empty string if input falsy.

Throws

{none}:

isIgnoredDirName [Utility]

Name:

isIgnoredDirName

File:

engine.js

Type:

Utility

Description:

Check whether a single directory name should be ignored (exact match against IGNORED_DIRS).

Parameters

Name	Type	Description
`{string} name - The directory entry name (not full path).`	any

Returns

Type:

boolean

Description:

- True if the name is in the ignored set.

Throws

{none}:

shouldIgnore [Utility]

Name:

shouldIgnore

File:

engine.js

Type:

Utility

Description:

Determine whether a full path should be ignored based on substrings in IGNORE_PATH_PARTS.

Parameters

Name	Type	Description
`{string} fullPath - Full file or directory path to test.`	any

Returns

Type:

boolean

Description:

- True if any ignored path part is present in fullPath.

Throws

{none}:

isCodeFile [Utility]

Name:

isCodeFile

File:

engine.js

Type:

Utility

Description:

Determine if a file path corresponds to a source code file based on extension whitelist.

Parameters

Name	Type	Description
`{string} filePath - Full or relative path to a file.`	any

Returns

Type:

boolean

Description:

- True if file extension is recognized as source code.

Throws

{none}:

walkDir [Utility]

Name:

walkDir

File:

engine.js

Type:

Utility

Description:

Recursively walk a directory tree starting at startPath and collect code file paths.

Parameters

Name	Type	Description
`{string} startPath - Root directory to start walking.`	any

Returns

Type:

string[]

Description:

- Array of file paths that are considered code files (per isCodeFile).

Throws

{none} - Filesystem errors are caught and result in skipping entries; does not throw.:

detectLanguage [Utility]

Name:

detectLanguage

File:

engine.js

Type:

Utility

Description:

Map a file extension to a language/runtime identifier used by downstream tooling.

Parameters

Name	Type	Description
`{string} filePath - File path used to extract extension.`	any

Returns

Type:

string

Description:

- Language key (e.g., "node", "go", "python", "rust", etc.).

Throws

{none}:

chatCompletion [Utility]

Name:

chatCompletion

File:

engine.js

Type:

Utility

Description:

Simple async wrapper around OpenAI chat completions that returns plain text.

Parameters

Name	Type	Description
`{Object} options`	any
`{string} options.system - System prompt content (will be trimmed).`	any
`{string} options.user - User prompt content (will be trimmed).`	any
`{number} [options.temperature=1] - Sampling temperature passed to the model.`	any
`{string} [options.model=MODEL_NAME] - Model identifier to use for the completion.`	any

Returns

Type:

Promise<string>

Description:

- Resolved plain-text content from the first choice with code fences removed.

Throws

{Error} - Propagates errors from OpenAI SDK/network; calling code should handle API errors.:

chatJSON [Utility]

Name:

chatJSON

File:

engine.js

Type:

Utility

Description:

Wrapper around chatCompletion that expects the model response to be STRICT JSON.

Parameters

Name	Type	Description
`{Object} options`	any
`{string} options.system - System prompt passed to chatCompletion.`	any
`{string} options.user - User prompt passed to chatCompletion.`	any
`{number} [options.temperature=1] - Sampling temperature forwarded to chatCompletion.`	any
`{string} [options.model=MODEL_NAME] - Model identifier forwarded to chatCompletion.`	any

Returns

Type:

Promise<any>

Description:

- Parsed JSON object returned by the model.

Throws

{Error} - Throws an Error with details if JSON.parse fails (includes raw model output).:

listFiles [Utility]

Name:

listFiles

File:

extract-docblocks.js

Type:

Utility

Description:

Recursively scan a directory and return a flat list of JavaScript (.js) file paths,

Parameters

Name	Type	Description
`{string} dir - The root directory to scan.`	any

Returns

Type:

string[]

Description:

Array of absolute or relative file paths (strings) that end with ".js".

Throws

{Error} Throws filesystem errors from fs.readdirSync if the directory cannot be read.:

extractDocblocks [Utility]

Name:

extractDocblocks

File:

extract-docblocks.js

Type:

Utility

Description:

Extract block-style JSDoc comment blocks (/** ... *\/) from a source string.

Parameters

Name	Type	Description
`{string} source - The source file contents to scan.`	any

Returns

Type:

{raw: string, start: number

Description:

[]} Array of extracted docblock objects with:

Throws

{Error} No explicit throws, but will propagate errors if incorrect input types are used.:

detectFunctionName [Utility]

Name:

detectFunctionName

File:

extract-docblocks.js

Type:

Utility

Description:

Heuristically detect the JavaScript function or identifier name that immediately

Parameters

Name	Type	Description
`{string} source - The complete source text to scan.`	any
`{number} pos - The character index in source from which to start scanning (typically the end of a docblock).`	any

Returns

Type:

string|null

Description:

The detected function/identifier name or null if none matches.

Throws

{Error} Will not explicitly throw; may propagate if invalid args are provided.:

processFile [Utility]

Name:

processFile

File:

extract-docblocks.js

Type:

Utility

Description:

Read a JavaScript file, extract docblocks, parse each docblock with the imported

Parameters

Name	Type	Description
`{string} file - File path to read and process.`	any
`{Array<Object>} allBlocks - Mutable array that will receive parsed docblock summary objects.`	any

Returns

Type:

void

Throws

{Error} Propagates errors from fs.readFileSync and parseDocblock.:

printViolationsSummary [Utility]

Name:

printViolationsSummary

File:

extract-violations.js

Type:

Utility

Description:

Produce a human-readable summary of the violations grouped by severity and print to stdout.

Parameters

Name	Type	Description
`{Array<Object>} violations - Array of violation objects produced by analyzeViolations.`	any

Returns

Type:

void

extractClasses [Utility]

Name:

extractClasses

File:

extract.js

Type:

Utility

Description:

Parse source file content and extract top-level class/struct names for supported languages.

Parameters

Name	Type	Description
`{string} content - The full source file content.`	any
`{string} ext - File extension (e.g. ".js", ".ts", ".go", ".dart").`	any

Returns

Type:

string[]

Description:

Array of unique class/struct names (max 50). Names preserved as declared.

Throws

{none}:

extractFunctions [Utility]

Name:

extractFunctions

File:

extract.js

Type:

Utility

Description:

Analyze source content and return a list of top-level functions and methods with metadata.

Parameters

Name	Type	Description
`{string} content - Full source file content.`	any
`{string} ext - File extension to guide parsing rules (".go", ".js", ".ts", ".jsx", ".tsx").`	any

Returns

Type:

Array<Object>

Description:

Array of function descriptors:

Throws

{none}:

within [Utility]

Name:

within

File:

extract.js

Type:

Utility

Description:

Return a short slice of content starting at startIndex for heuristic analysis.

Parameters

Name	Type	Description
`{string} content - Full source text.`	any
`{number} startIndex - Start index within the content.`	any

Returns

Type:

string

Description:

Substring of content from startIndex up to 300 characters or end of content.

Throws

{none}:

extractImports [Utility]

Name:

extractImports

File:

extract.js

Type:

Utility

Description:

Extract import/module dependency specifiers from source content for JS/TS/Go/Dart.

Parameters

Name	Type	Description
`{string} content - Full source file content.`	any
`{string} ext - File extension (".js", ".ts", ".dart", ".go", etc.)`	any

Returns

Type:

string[]

Description:

Array of import module paths or packages (max 50 entries).

Throws

{none}:

extractEndpoints [Utility]

Name:

extractEndpoints

File:

extract.js

Type:

Utility

Description:

Heuristically extract network endpoints (URLs and route definitions) from source content.

Parameters

Name	Type	Description
`{string} content - File contents to scan.`	any
`{string} ext - File extension to tune Go detection.`	any

Returns

Type:

Array<Object>

Description:

Array of endpoint descriptors:

Throws

{none}:

extractLanguageSpecific [Utility]

Name:

extractLanguageSpecific

File:

extract.js

Type:

Utility

Description:

Extract language-specific artifacts from a file: Go structs, Node models/routes, Flutter/Dart classes and fields.

Parameters

Name	Type	Description
`{string} content - File content.`	any
`{string} filePath - Full or basename of file (used to infer default model names).`	any
`{string} ext - File extension.`	any

Returns

Type:

Object

Description:

Language specific extraction results depending on extension.

Throws

{none}:

extractGo [Utility]

Name:

extractGo

File:

extract.js

Type:

Utility

Description:

Parse Go source content to extract package name, struct type definitions and HTTP handler functions.

Parameters

Name	Type	Description
`{string} content - Go source code text.`	any

Returns

Type:

Object

Description:

{ packageName: string|null, structs: Array, handlers: Array }

Throws

{none}:

extractNode [Utility]

Name:

extractNode

File:

extract.js

Type:

Utility

Description:

Parse Node/JS/TS content to find Mongoose-like schema blocks, models, express routes and middleware.

Parameters

Name	Type	Description
`{string} content - Source file content.`	any
`{string} [filename=""] - Filename used to infer default model names when model declarations are absent.`	any

Returns

Type:

Object

Description:

result containing:

Throws

{none}:

extractSchemaFields [Utility]

Name:

extractSchemaFields

File:

extract.js

Type:

Utility

Description:

Parse a snippet that represents a schema object and extract field name/type pairs.

Parameters

Name	Type	Description
`{string} schemaString - Raw schema object source text (may contain comments and whitespace).`	any

Returns

Type:

Array<Object>

Description:

Array of fields: [{ name: string, type: string }]

Throws

{none}:

isIgnoredDirName [Utility]

Name:

isIgnoredDirName

File:

generate-comments.js

Type:

Utility

Description:

Check whether a directory entry name should be ignored based on the IGNORED_DIRS set.

Parameters

Name	Type	Description
`{string} name - Directory or entry name (not a path) to test (e.g. "node_modules").`	any

Returns

Type:

boolean

Description:

true if the name is in the IGNORED_DIRS set, false otherwise.

Throws

None:

shouldIgnore [Utility]

Name:

shouldIgnore

File:

generate-comments.js

Type:

Utility

Description:

Determine whether a full filesystem path should be skipped based on IGNORE_PATH_PARTS.

Parameters

Name	Type	Description
`{string} fullPath - Absolute or relative filesystem path to evaluate.`	any

Returns

Type:

boolean

Description:

true if any configured ignore substring is present in fullPath.

Throws

None:

isCodeFile [Utility]

Name:

isCodeFile

File:

generate-comments.js

Type:

Utility

Description:

Quick heuristic to determine whether a given path refers to a source code file

Parameters

Name	Type	Description
`{string} filePath - File path to inspect.`	any

Returns

Type:

boolean

Description:

true if the extension is recognized as a code extension and not excluded.

Throws

None:

stripCodeFences [Utility]

Name:

stripCodeFences

File:

generate-comments.js

Type:

Utility

Description:

Remove leading/trailing Markdown code-fences (```...```) from a string and trim whitespace.

Parameters

Name	Type	Description
`{string} text - Potentially fenced text returned by an LLM or other source.`	any

Returns

Type:

string

Description:

Text with surrounding fences removed and trimmed; returns empty string for falsy input.

Throws

None:

walkDir [Utility]

Name:

walkDir

File:

generate-comments.js

Type:

Utility

Description:

Recursively walk a starting directory and collect all files that are considered code files.

Parameters

Name	Type	Description
`{string} startPath - Path to begin recursion from. Can be relative or absolute.`	any

Returns

Type:

string[]

Description:

Array of file paths that match isCodeFile. Order is deterministic based on fs.readdirSync.

Throws

Will not throw on typical filesystem access errors — errors are caught and directories/files skipped.:

detectLanguage [Utility]

Name:

detectLanguage

File:

generate-comments.js

Type:

Utility

Description:

Map file extensions to a short language key used to select prompts and parsing behavior.

Parameters

Name	Type	Description
`{string} filePath - Path or filename whose extension will be inspected.`	any

Returns

Type:

string

Description:

One of: "js", "go", "dart", "swift", "kotlin", "c", "csharp", "python", "php", "rust", "objc", "shell", or "generic".

Throws

None:

getDocSystemPrompt [Utility]

Name:

getDocSystemPrompt

File:

generate-comments.js

Type:

Utility

Description:

Return a language-specific system prompt for the documentation generation model.

Parameters

Name	Type	Description
`{string} lang - Language key returned by detectLanguage (e.g. "js", "go", "dart").`	any

Returns

Type:

string

Description:

System prompt tailored to the given language; defaults to a generic instruction set.

Throws

None:

getMetaSystemPrompt [Utility]

Name:

getMetaSystemPrompt

File:

generate-comments.js

Type:

Utility

Description:

Produce the system prompt used to instruct the model to extract structured metadata

Parameters

Name	Type	Description
`{string} lang - Language key used to contextualize prompts (informational).`	any

Returns

Type:

string

Description:

System prompt instructing the model to return STRICT JSON with "api" and "models" arrays.

Throws

None:

generateDocForFile [Utility]

Name:

generateDocForFile

File:

generate-comments.js

Type:

Utility

Description:

Use the OpenAI Chat Completions API to request insertion of doc-blocks into a source file.

Parameters

Name	Type	Description
`{string} filePath - The file path being documented (used for logging/context only).`	any
`{string} source - The original source content of the file.`	any
`{string} lang - Language key used to select the system prompt.`	any

Returns

Type:

Promise<string>

Description:

Resolves to the updated file content as a string (code fences stripped). This is expected to be the FULL FILE CONTENT with doc-blocks inserted.

Throws

Will propagate errors from the OpenAI client (network, auth, or API errors).:

extractMetadataForFile [Utility]

Name:

extractMetadataForFile

File:

generate-comments.js

Type:

Utility

Description:

Use the OpenAI Chat Completions API to extract structured metadata (api endpoints and models)

Parameters

Name	Type	Description
`{string} filePath - Path to the file being analyzed (used for logging/context).`	any
`{string} source - The file contents (preferably updated with doc-blocks).`	any
`{string} lang - Language key used to contextualize the prompt.`	any

Returns

Type:

Promise<{api: any[], models: any[]

Description:

>} Parsed JSON object containing "api" and "models" arrays. If parsing fails, returns { api: [], models: [] } and logs a warning.

Throws

Will propagate OpenAI API errors. JSON.parse errors are caught and logged; the function returns an empty metadata structure on parse failure.:

escapeHtml [Utility]

Name:

escapeHtml

File:

generate-doc-html.js

Type:

Utility

Parameters

Name	Type	Description
`{string} text - The input text that may contain HTML-sensitive characters`	any

Returns

Type:

string

Description:

Escaped string safe for HTML contexts. Returns empty string for falsy input.

Throws

None:

generateCSS [Utility]

Name:

generateCSS

File:

generate-doc-html.js

Type:

Utility

Parameters

Name	Type	Description
None (reads global `data` but does not mutate it)	any

Returns

Type:

string

Description:

CSS string to be embedded in a <style> tag in the generated HTML

Throws

None:

generateNav [Utility]

Name:

generateNav

File:

generate-doc-html.js

Type:

Utility

Parameters

Name	Type	Description
None (reads global `data` object)	any

Returns

Type:

string

Description:

HTML string containing the sidebar markup including a search input and section counts

Throws

None:

generateServers [Utility]

Name:

generateServers

File:

generate-doc-html.js

Type:

Utility

Parameters

Name	Type	Description
None (reads global `data.servers` array)	any

Returns

Type:

string

Description:

HTML string representing the SERVERS section with expandable details per server

Throws

None:

generateMounts [Utility]

Name:

generateMounts

File:

generate-doc-html.js

Type:

Utility

Parameters

Name	Type	Description
None (reads global `data.mounts`)	any

Returns

Type:

string

Description:

HTML markup for the MOUNTS section including per-mount route lists

Throws

None:

generateRoutes [Utility]

Name:

generateRoutes

File:

generate-doc-html.js

Type:

Utility

Parameters

Name	Type	Description
None (reads global `data.routes`)	any

Returns

Type:

string

Description:

HTML string for the ROUTES section with parameter/return/throws/models/apis subsections

Throws

None:

generateModels [Utility]

Name:

generateModels

File:

generate-doc-html.js

Type:

Utility

Parameters

Name	Type	Description
None (reads global `data.models`)	any

Returns

Type:

string

Description:

HTML markup for the MODELS section with tables and usage lists

Throws

None:

generateAPIs [Utility]

Name:

generateAPIs

File:

generate-doc-html.js

Type:

Utility

Parameters

Name	Type	Description
None (reads global `data.apis`)	any

Returns

Type:

string

Description:

HTML markup for the EXTERNAL APIS section including per-endpoint usage lists

Throws

None:

generateFunctions [Utility]

Name:

generateFunctions

File:

generate-doc-html.js

Type:

Utility

Parameters

Name	Type	Description
None (reads global `data.functions`)	any

Returns

Type:

string

Description:

HTML markup for the FUNCTIONS section

Throws

None:

generateMiddleware [Utility]

Name:

generateMiddleware

File:

generate-doc-html.js

Type:

Utility

Parameters

Name	Type	Description
None (reads global `data.middleware`)	any

Returns

Type:

string

Description:

HTML markup for the MIDDLEWARE section

Throws

None:

generateDatabases [Utility]

Name:

generateDatabases

File:

generate-doc-html.js

Type:

Utility

Parameters

Name	Type	Description
None (reads global `data.databases`)	any

Returns

Type:

string

Description:

HTML for DATABASES section

Throws

None:

generateClusters [Utility]

Name:

generateClusters

File:

generate-doc-html.js

Type:

Utility

Parameters

Name	Type	Description
None (reads global `data.clusters`)	any

Returns

Type:

string

Description:

HTML markup for the CLUSTERS section

Throws

None:

generateSockets [Utility]

Name:

generateSockets

File:

generate-doc-html.js

Type:

Utility

Parameters

Name	Type	Description
None (reads global `data.sockets`)	any

Returns

Type:

string

Description:

HTML markup for the SOCKETS section

Throws

None:

generateHTML [Utility]

Name:

generateHTML

File:

generate-doc-html.js

Type:

Utility

Parameters

Name	Type	Description
None (reads global `data` and uses helper functions: generateCSS, generateNav, generateServers, etc.)	any

Returns

Type:

string

Description:

Full HTML document string (<!DOCTYPE html>...)</string>

Throws

None:

hasDocumentation [Utility]

Name:

hasDocumentation

File:

generate-docs.js

Type:

Utility

Description:

Analyze a source file string and determine whether it already

Parameters

Name	Type	Description
`{string} source - Full file source code to inspect.`	any

Returns

Type:

boolean

Description:

Returns true if the source contains at least 3 docblocks

Throws

{none} This function performs pure string analysis and does not throw.:

count [Utility]

Name:

count

File:

generate-report.js

Type:

Utility

Description:

Safely counts elements in an array-like value.

Parameters

Name	Type	Description
`{any} arr - Value expected to be an array; if not an array returns 0.`	any

Returns

Type:

number

Description:

Number of items in arr if array, otherwise 0.

diffList [Utility]

Name:

diffList

File:

generate-report.js

Type:

Utility

Description:

Produce and print lists of added/removed items between two nodeStructure lists keyed by `key` (e.g., routes, models, servers).

Parameters

Name	Type	Description
`{string} key - Name of the nodeStructure array to diff (e.g., "routes" or "models").`	any

Returns

Type:

void

Description:

Prints added/removed items to stdout.

Throws

none:

addApiToCatalog [Utility]

Name:

addApiToCatalog

File:

generate-report.js

Type:

Utility

Description:

Add a deduplicated API entry to an in-memory catalog keyed by "METHOD url". Tracks which service used the API.

Parameters

Name	Type	Description
`{Object} param0 - Input object`	any
`{string} [param0.method="GET"] - HTTP method for the API endpoint.`	any
`{string} [param0.url=""] - URL or path of the API endpoint.`	any
`{string\|null} [param0.sourceService=null] - Optional service name that uses this API.`	any

Returns

Type:

void

Throws

none - Silently ignores invalid or empty URLs.:

escapeHtml [Utility]

Name:

escapeHtml

File:

generate-report.js

Type:

Utility

Description:

Escape characters in a string for safe insertion into HTML content to prevent markup injection.

Parameters

Name	Type	Description
`{string} [text=""] - Input string to escape.`	any

Returns

Type:

string

Description:

Escaped HTML string where &, <, >, ", ' are replaced by corresponding entities.

Throws

none:

anchorId [Utility]

Name:

anchorId

File:

generate-report.js

Type:

Utility

Description:

Generate a safe anchor/id string by combining a prefix and a sanitized name. Removes non-alphanumeric characters from name.

Parameters

Name	Type	Description
`{string} prefix - Identifier prefix (e.g., "service", "api").`	any
`{string} [name=""] - Name or path component to include in the id.`	any

Returns

Type:

string

Description:

Concatenated id string suitable for use in HTML id attributes.

navBar [Utility]

Name:

navBar

File:

generate-report.js

Type:

Utility

Description:

Render a small HTML navigation bar used across generated report pages.

Parameters

Name	Type	Description
`none`	any

Returns

Type:

string

Description:

HTML fragment for the top navigation controls.

baseCss [Utility]

Name:

baseCss

File:

generate-report.js

Type:

Utility

Description:

Returns the base CSS stylesheet used by all generated HTML pages.

Parameters

Name	Type	Description
`none`	any

Returns

Type:

string

Description:

CSS content string.

baseJs [Utility]

Name:

baseJs

File:

generate-report.js

Type:

Utility

Description:

Returns a small JS snippet used across the generated HTML pages for toggling sections and initial UI state.

Parameters

Name	Type	Description
`none`	any

Returns

Type:

string

Description:

JavaScript code string.

pageTemplate [Utility]

Name:

pageTemplate

File:

generate-report.js

Type:

Utility

Description:

Compose a full HTML page using provided title/header/body and optionally include high-level analysis stats.

Parameters

Name	Type	Description
`{string} title - Page title used in <title>.`	any
`{string} headerBlock - Heading displayed at top of the page.`	any
`{string} body - Main body HTML fragment.`	any
`{boolean} [includeStats=false] - Whether to include a stats block derived from analysis.`	any

Returns

Type:

string

Description:

Full HTML document string.

renderServicesSection [Utility]

Name:

renderServicesSection

File:

generate-report.js

Type:

Utility

Description:

Render a collapsible HTML section listing available services with links to their documentation blocks.

Parameters

Name	Type	Description
`{string} title - Section title text.`	any
`{Array<Object>} items - Array of service objects: { name, purpose, path }.`	any

Returns

Type:

string

Description:

HTML fragment for the services section (empty string if no items).

renderApiCatalogSection [Utility]

Name:

renderApiCatalogSection

File:

generate-report.js

Type:

Utility

Description:

Render an API catalog grouped by domain/origin. Each endpoint contains method, url, and list of services that use it.

Parameters

Name	Type	Description
`{string} title - Section title.`	any
`{Array<Object>} endpoints - Array of { method, url, usedBy } entries.`	any

Returns

Type:

string

Description:

HTML fragment for the API catalog (empty string if no endpoints).

renderServiceDocs [Utility]

Name:

renderServiceDocs

File:

generate-report.js

Type:

Utility

Description:

Render detailed service and API documentation sections from documentation data. Supports methods, params, returns and endpoints.

Parameters

Name	Type	Description
`{Array<Object>} docs - Array of service documentation objects. Each may contain { name, path, purpose, endpoints[], methods[] }.`	any

Returns

Type:

string

Description:

HTML fragment representing documentation for each service (empty string if none).

renderModelsStructsBlock [Utility]

Name:

renderModelsStructsBlock

File:

generate-report.js

Type:

Utility

Description:

Render a combined Models/Structs/Flutter classes block. Reads model/struct lists from analysis and generates field/index tables.

Parameters

Name	Type	Description
`none - Reads analysis.* structures from outer scope.`	any

Returns

Type:

string

Description:

HTML fragment describing Node models, Go structs, and Flutter models found in the analysis.

renderViolation [Utility]

Name:

renderViolation

File:

generate-report.js

Type:

Utility

Description:

Render a single violation object as an HTML block including severity, file path, message, code excerpt and suggestion.

Parameters

Name	Type	Description
`{Object} v - Violation object: { severity, file, line, message, code, suggestion, shouldUse }.`	any

Returns

Type:

string

Description:

HTML fragment for the provided violation.

renderIssuesBySeverity [Utility]

Name:

renderIssuesBySeverity

File:

generate-report.js

Type:

Utility

Description:

Render a set of collapsible sections for violations grouped by severity (critical, high, medium, low).

Parameters

Name	Type	Description
`none - Uses top-level violationsBySeverity variable.`	any

Returns

Type:

string

Description:

HTML fragment containing sections per severity (empty string if none).

renderDocumentationSummary [Utility]

Name:

renderDocumentationSummary

File:

generate-report.js

Type:

Utility

Description:

Render a summary section using documentation.json content. Outputs Routes, Servers, Models, Functions, and File Descriptions blocks.

Parameters

Name	Type	Description
`none - Uses docsJson variable from outer scope.`	any

Returns

Type:

string

Description:

HTML fragment summarizing documentation entries. May contain multiple collapsible subsections or return empty string sections if no data present.

renderCrossRefsPage [Utility]

Name:

renderCrossRefsPage

File:

generate-report.js

Type:

Utility

Description:

Render cross-reference mappings (route→models, route→collections, model→routes, mount→routes, external APIs) as collapsible sections.

Parameters

Name	Type	Description
`none - Uses xrefs variable from outer scope which may contain various mapping objects.`	any

Returns

Type:

string

Description:

HTML fragment with multiple map sections based on available cross-reference data.

generateSection [Utility]

Name:

generateSection

File:

generate-violations-report.js

Type:

Utility

Parameters

Name	Type	Description
`{string} severity - Severity key used for CSS classes and badges ('critical'\|'high'\|'medium'\|'low').`	any
`{string} title - Display title for the section header (human readable).`	any
`{Array<Object>} items - Array of violation objects to render. Expected fields on each violation:`	any

Returns

Type:

string

Description:

HTML fragment as string representing the complete section (header + content).

Throws

{TypeError} If items is not iterable (e.g. null/undefined) the internal map() will throw.:

escapeHtml [Utility]

Name:

escapeHtml

File:

generate-violations-report.js

Type:

Utility

Parameters

Name	Type	Description
`{string} text - Input string containing arbitrary characters that will be rendered in HTML context.`	any

Returns

Type:

string

Description:

Escaped string where &, <, >, ", and ' are replaced with their corresponding HTML entities.

Throws

{TypeError} If text is not a string and does not implement replace, this will throw when calling replace.:

safeList [Utility]

Name:

safeList

File:

save-context.js

Type:

Utility

Parameters

Name	Type	Description
`{Object} obj - Source object to read property from`	any
`{string} key - Property key expected to contain an array`	any

Returns

Type:

Array

Description:

- Returns obj[key] if it's an array, otherwise an empty array

Throws

- None:

describeServicePurpose [Utility]

Name:

describeServicePurpose

File:

save-context.js

Type:

Utility

Parameters

Name	Type	Description
`{Object} service - Service descriptor object (expects at least a 'name' field)`	any
`{string} service.name - The service/class name used to infer purpose`	any

Returns

Type:

string

Description:

- Short human-readable description of the service's likely responsibility

Throws

- None:

sanitizeId [Utility]

Name:

sanitizeId

File:

smart-analyze.js

Type:

Utility

Description:

Normalize a string to a lowercase dash-separated identifier safe for anchors/ids.

Parameters

Name	Type	Description
`{string} str - Input string to normalize (file name, route, etc.).`	any

Returns

Type:

string

Description:

Sanitized id string (lowercase, non-alphanumerics replaced with '-').

Throws

Will not throw; defensive trimming applied.:

generateId [Utility]

Name:

generateId

File:

smart-analyze.js

Type:

Utility

Description:

Generate a stable id string for various entity types used in the documentation structure.

Parameters

Name	Type	Description
`{string} type - One of: server, mount, route, model, api, function, middleware, database, cluster, socket.`	any
`{Object} data - Context object containing identifying fields (e.g., port, path, method, name, url, file).`	any

Returns

Type:

string

Description:

Generated id string prefixed with the entity type.

Throws

Will not throw; unknown types fall back to sanitized type string.:

parseParams [Utility]

Name:

parseParams

File:

smart-analyze.js

Type:

Utility

Description:

Parse an array of parameter doc strings into structured { name, type, description } objects.

Parameters

Name	Type	Description
`{string[]\|undefined} paramArray - Array of param doc strings, e.g. "id`	number	resource id".

Returns

Type:

Array<{name:string,type:string,description:string

Description:

>} Parsed parameter descriptors or [] if none.

Throws

Will not throw; unknown formats return name only with type "any".:

parseReturns [Utility]

Name:

parseReturns

File:

smart-analyze.js

Type:

Utility

Description:

Parse return documentation into a structured object with HTTP code, type and description.

Parameters

Name	Type	Description
`{string[]\|undefined} returnArray - Array containing return doc string, e.g. "200 {object} Success payload".`	any

Returns

Type:

{code:string,type:string,description:string

Description:

|null} Parsed return descriptor or null if none.

Throws

Will not throw; fallback to code "200" and type "unknown" for unparseable input.:

parseThrows [Utility]

Name:

parseThrows

File:

smart-analyze.js

Type:

Utility

Description:

Parse thrown errors documentation into structured { code, description } items.

Parameters

Name	Type	Description
`{string[]\|undefined} throwsArray - Array of throw doc strings, e.g. "404 - Not Found".`	any

Returns

Type:

Array<{code:string,description:string

Description:

>} Parsed throws or [] if none.

Throws

Will not throw; unparseable lines are returned with code equal to the raw string.:

parseSchema [Utility]

Name:

parseSchema

File:

smart-analyze.js

Type:

Utility

Description:

Parse a simple schema definition string into an array of field descriptors.

Parameters

Name	Type	Description
`{string\|undefined} schemaString - Comma-separated fields like "name`	String,	age:Number".

Returns

Type:

Array<{field:string,type:string

Description:

>} Parsed schema fields, empty array if none.

Throws

Will not throw; missing type defaults to "String".:

parseRoute [Utility]

Name:

parseRoute

File:

smart-analyze.js

Type:

Utility

Description:

Parse a route declaration string into method and path. Supports "GET /path" style.

Parameters

Name	Type	Description
`{string} routeString - Route string, e.g. "GET /users/`	id"	or just "/users".

Returns

Type:

{method:string,path:string

Description:

} Parsed HTTP method and path (default method GET).

Throws

Will not throw; unknown formats default to GET and the full string as path.:

extractServers [Utility]

Name:

extractServers

File:

smart-analyze.js

Type:

Utility

Description:

Extract server definitions (port, protocol, cluster, workers, database) from docblocks.

Parameters

Name	Type	Description
`{Array<Object>} docblocks - Array of parsed docblock objects with tags and file metadata.`	any

Returns

Type:

Array<Object>

Description:

Array of server descriptors { file, port, protocol, cluster, workers, database, id }.

Throws

Will not throw; entries without port are filtered out.:

extractMounts [Utility]

Name:

extractMounts

File:

smart-analyze.js

Type:

Utility

Description:

Extract Express mount points from docblocks (tag: @mount) and associated router info.

Parameters

Name	Type	Description
`{Array<Object>} docblocks - Array of docblock entries.`	any

Returns

Type:

Array<Object>

Description:

Array of mounts { path, router, file, id }.

Throws

Will not throw.:

extractModels [Utility]

Name:

extractModels

File:

smart-analyze.js

Type:

Utility

Description:

Extract model/schema declarations from docblocks (tags: @model, @collection, @schema, @indexes).

Parameters

Name	Type	Description
`{Array<Object>} docblocks - Array of docblocks.`	any

Returns

Type:

Array<Object>

Description:

Array of model descriptors:

Throws

Will not throw; entries lacking name/collection are ignored.:

extractAPIs [Utility]

Name:

extractAPIs

File:

smart-analyze.js

Type:

Utility

Description:

Group external API usages (tag: @api) by domain, collect endpoints and usage locations.

Parameters

Name	Type	Description
`{Array<Object>} docblocks - Array of docblocks; uses description and tags.purpose where available.`	any

Returns

Type:

Array<Object>

Description:

Array of api groups:

Throws

Will not throw; malformed URLs are treated as single-domain entries.:

extractFunctions [Utility]

Name:

extractFunctions

File:

smart-analyze.js

Type:

Utility

Description:

Extract non-route functions from docblocks and infer their type (API Integration, Data Service, etc.).

Parameters

Name	Type	Description
`{Array<Object>} docblocks - Array of docblocks (function != "file-level").`	any

Returns

Type:

Array<Object>

Description:

Array of function descriptors:

Throws

Will not throw.:

extractMiddleware [Utility]

Name:

extractMiddleware

File:

smart-analyze.js

Type:

Utility

Description:

Extract documented middleware entries (tag: @middleware) including purpose and file.

Parameters

Name	Type	Description
`{Array<Object>} docblocks - Array of parsed docblocks.`	any

Returns

Type:

Array<Object>

Description:

Array of middleware descriptors { name, purpose, file, id }.

Throws

Will not throw.:

extractDatabases [Utility]

Name:

extractDatabases

File:

smart-analyze.js

Type:

Utility

Description:

Group database usage information (tags: @database, @dbname, @host, @authSource, @replicaSet) by dbname.

Parameters

Name	Type	Description
`{Array<Object>} docblocks - Array of docblocks referencing DBs.`	any

Returns

Type:

Array<Object>

Description:

Array of database descriptors { name, host, authSource, replicaSet, files[], id }.

Throws

Will not throw.:

extractClusters [Utility]

Name:

extractClusters

File:

smart-analyze.js

Type:

Utility

Description:

Aggregate cluster-related docblocks (tag: @cluster) into cluster descriptors with worker counts and files.

Parameters

Name	Type	Description
`{Array<Object>} docblocks - Array of docblocks.`	any

Returns

Type:

Array<Object>

Description:

Array of cluster descriptors { mode, workers, files[], id }.

Throws

Will not throw.:

extractSockets [Utility]

Name:

extractSockets

File:

smart-analyze.js

Type:

Utility

Description:

Extract socket event documentation (tags: @socket, @emits, @events) into socket descriptors.

Parameters

Name	Type	Description
`{Array<Object>} docblocks - Array of docblocks.`	any

Returns

Type:

Array<Object>

Description:

Array of socket descriptors { event, file, function, purpose, id }.

Throws

Will not throw.:

extractDomain [Utility]

Name:

extractDomain

File:

smart-analyze.js

Type:

Utility

Description:

Extract the host/domain portion from a URL string. Falls back to the input if not a URL.

Parameters

Name	Type	Description
`{string} url - Full URL or identifier.`	any

Returns

Type:

string

Description:

Domain name or original string when parsing fails.

Throws

Will not throw; exceptions caught and original URL returned.:

inferFunctionType [Utility]

Name:

inferFunctionType

File:

smart-analyze.js

Type:

Utility

Description:

Heuristically infer a function's role based on docblock tags and file path (API Integration, Data Service, Service Method, Utility).

Parameters

Name	Type	Description
`{Object} block - Docblock object with tags and file metadata.`	any

Returns

Type:

string

Description:

Inferred type label.

Throws

Will not throw.:

buildCrossReferences [Utility]

Name:

buildCrossReferences

File:

smart-analyze.js

Type:

Utility

Description:

Enrich the extracted structure with cross-references (anchors) between servers, mounts, routes, models, functions and APIs.

Parameters

Name	Type	Description
`{Object} structure - Object containing arrays: routes, models, apis, functions, mounts, servers.`	any

Returns

Type:

Object

Description:

The same structure reference with additional fields populated:

Throws

Will not throw; best-effort augmentation when link targets are missing.:

findViolations [Utility]

Name:

findViolations

File:

violations.js

Type:

Utility

Parameters

Name	Type	Description
	any

Returns

Type:

Array<Object>

Description:

Array of violation objects. Each object has the shape:

Throws

None - function performs only in-memory analysis and does not throw intentionally.:

add [Utility]

Name:

add

File:

violations.js

Type:

Utility

Parameters

Name	Type	Description
	any

Returns

Type:

unknown

Description:

void - pushes matching violation objects into the outer `violations` array.

Throws

None:

ROUTES

GET See each returned route.method + route.path for actual endpoints.

Method:

GET

Path:

See each returned route.method + route.path for actual endpoints.

File:

smart-analyze.js

Handler:

extractRoutes

Description:

Extract documented HTTP routes from docblocks (tag: @route) and parse parameters, returns, throws.

Parameters

Name	Type	Description
`{Array<Object>} docblocks - Array of docblocks with tags like @route, @params, @returns, @models.`	any

Returns

Status:

200

Type:

Array<Object>

Description:

Array of route descriptors with fields:

Errors

Code	Description
Will not throw; returns empty array if none.

MODELS

Schema extraction attempts to map field name -> type and common options (required, default, lowercase) (Mongoose models (inferred) - model.name corresponds to mongoose.model('<name>', Schema))

Model:

Schema extraction attempts to map field name -> type and common options (required, default, lowercase)

Collection:

Mongoose models (inferred) - model.name corresponds to mongoose.model('<name>', Schema)

File:

extract.js

Description:

Parse Node/JS/TS content to find Mongoose-like schema blocks, models, express routes and middleware.

Schema and field information rendered as table rows (When model.collection is present, shown in UI but not modified)

Model:

Schema and field information rendered as table rows

Collection:

When model.collection is present, shown in UI but not modified

File:

generate-doc-html.js

Schema/model descriptor representing fields and indexes. (When present, collection property maps to the Mongo collection name.)

Model:

Schema/model descriptor representing fields and indexes.

Collection:

When present, collection property maps to the Mongo collection name.

File:

smart-analyze.js

Description:

Extract model/schema declarations from docblocks (tags: @model, @collection, @schema, @indexes).

When present, files list the source files interacting with the DB. (When present, files list the source files interacting with the DB.)

Collection:

When present, files list the source files interacting with the DB.

File:

smart-analyze.js

Description:

Group database usage information (tags: @database, @dbname, @host, @authSource, @replicaSet) by dbname.

CATEGORIES

PIPELINE

Utilities (118 functions)