@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/managers/PolicyEvaluator.d.ts

@@ -0,0 +1,213 @@
+import BaseManager from './BaseManager.js';
+import type { Policy, PolicySubject, PolicyResource } from '../types/Policy.js';
+import { WikiEngine } from '../types/WikiEngine.js';
+/**
+ * User context for policy evaluation
+ */
+interface UserContext {
+    username?: string;
+    roles?: string[];
+    [key: string]: unknown;
+}
+/**
+ * Policy subject definition
+ */
+/**
+ * What the request knows about the resource beyond its name, supplied by the
+ * PIP (#1504): today a page's `system-category`.
+ */
+export type ResourceAttributes = Record<string, unknown>;
+/**
+ * Access evaluation context
+ */
+interface AccessContext {
+    pageName: string;
+    action: string;
+    userContext?: UserContext;
+    attributes?: ResourceAttributes;
+}
+/**
+ * How each policy resource type matches (#1504). The TYPES are declared in
+ * configuration, `ngdpbase.access.resource-types`, and read through
+ * ConfigurationManager; how a type matches is code, one matcher per type. A
+ * type that is not declared, or that has no matcher here, never matches — a
+ * policy naming it decides nothing (docs/access-policies.md).
+ */
+export declare const RESOURCE_MATCHERS: Record<string, (pattern: string, pageName: string, attributes?: ResourceAttributes) => boolean>;
+/**
+ * The resource types configuration declares (#1504), for the evaluator and the
+ * validator alike. When the key is not set at all — a configuration older than
+ * it — the matchers' own types apply, so an older site keeps deciding as it
+ * did; PolicyEvaluator.initialize() warns.
+ */
+export declare function declaredResourceTypes(getProperty: (key: string, defaultValue: unknown) => unknown): Set<string>;
+/**
+ * Access evaluation result
+ */
+interface EvaluationResult {
+    hasDecision: boolean;
+    allowed: boolean;
+    reason: string;
+    policyName: string | null;
+}
+/**
+ * PolicyEvaluator - Evaluates access policies against a given context.
+ *
+ * PolicyEvaluator mimics how JSPWiki uses Java's built-in security framework
+ * (java.security) to load and evaluate security policies from a policy file.
+ * It evaluates policies in priority order and returns the first matching policy's
+ * decision.
+ *
+ * @class PolicyEvaluator
+ * @extends BaseManager
+ *
+ * @property {ConfigurationManager | null} configManager - Where the policies are read, live (#1431)
+ *
+ * @see {@link BaseManager} for base functionality
+ * @see {@link PolicyDecisionPoint.policies} for how the policies are read
+ * @see {@link PolicyInformationPoint} for access control integration
+ *
+ * @example
+ * const evaluator = engine.getManager('PolicyEvaluator');
+ * const result = await evaluator.evaluateAccess({
+ *   pageName: 'Main',
+ *   action: 'page:read',
+ *   userContext: { username: 'admin', roles: ['admin'] }
+ * });
+ * if (result.allowed) console.log('Access granted');
+ */
+declare class PolicyEvaluator extends BaseManager {
+    private configManager;
+    /**
+     * The policies in force NOW. Only the PDP interprets them (#1431 step 14b);
+     * this evaluator is the PDP's matching engine and asks it for the list, read
+     * live — PolicyManager used to hand back a copy taken at boot, so a policy
+     * edited in /admin/configuration was not enforced until a restart.
+     */
+    private policies;
+    /**
+     * Creates a new PolicyEvaluator instance
+     *
+     * @constructor
+     * @param {WikiEngine} engine - The wiki engine instance
+     */
+    constructor(engine: WikiEngine);
+    /**
+     * Initializes the PolicyEvaluator by getting its reference to ConfigurationManager
+     *
+     * @async
+     * @returns {Promise<void>}
+     * @throws {Error} If ConfigurationManager is not available
+     *
+     * @example
+     * await evaluator.initialize();
+     * console.log('Policy evaluator ready');
+     */
+    initialize(): Promise<void>;
+    /**
+     * Evaluates all relevant policies to make an access decision.
+     *
+     * Policies are evaluated in priority order (highest first). The first matching
+     * policy determines the access decision. If no policies match, access is denied.
+     *
+     * @async
+     * @param {AccessContext} context - The context of the access request
+     * @returns {Promise<EvaluationResult>} Evaluation result with decision and reason
+     *
+     * @example
+     * const result = await evaluator.evaluateAccess({
+     *   pageName: 'AdminPanel',
+     *   action: 'page:edit',
+     *   userContext: { username: 'user', roles: ['editor'] }
+     * });
+     * console.log('Allowed:', result.allowed, 'Reason:', result.reason);
+     */
+    evaluateAccess(context: AccessContext): Promise<EvaluationResult>;
+    /**
+     * Checks if a single policy matches the given context.
+     *
+     * A policy matches if ALL of the following conditions are true:
+     * - Subject matches (user has required role)
+     * - Resource matches (page name matches pattern)
+     * - Action matches (action is in policy's action list)
+     *
+     * @param {Policy} policy - The policy to check
+     * @param {AccessContext} context - The access request context
+     * @returns {boolean} True if the policy matches, false otherwise
+     *
+     * @example
+     * const matches = evaluator.matches(policy, context);
+     * if (matches) console.log('Policy applies to this request');
+     */
+    matches(policy: Policy, context: AccessContext): boolean;
+    /**
+     * Check if the user context's roles match the policy's subject requirements.
+     *
+     * A user matches if:
+     * - No subjects specified (applies to everyone), OR
+     * - Policy includes "All" role (applies to everyone), OR
+     * - User has at least one role matching a policy subject
+     *
+     * @param {PolicySubject[] | undefined} policySubjects - The subjects array from the policy
+     * @param {UserContext | undefined} userContext - The user's context
+     * @returns {boolean} True if the user matches the policy subjects
+     *
+     * @example
+     * const matches = evaluator.matchesSubject(
+     *   [{ type: 'role', value: 'admin' }],
+     *   { username: 'user', roles: ['admin', 'editor'] }
+     * );
+     * // matches === true
+     */
+    matchesSubject(policySubjects: PolicySubject[] | undefined, userContext: UserContext | undefined): boolean;
+    /**
+     * Checks if the resource matches the policy's resources.
+     *
+     * Uses glob pattern matching (via micromatch) to check if the page name
+     * matches any of the policy's resource patterns.
+     *
+     * @param {PolicyResource[] | undefined} resources - The resources array from the policy
+     * @param {string} pageName - The name of the page being accessed
+     * @returns {boolean} True if a resource matches the page
+     *
+     * @example
+     * const matches = evaluator.matchesResource(
+     *   [{ type: 'page', pattern: 'Admin*' }],
+     *   'AdminPanel'
+     * );
+     * // matches === true
+     */
+    /**
+     * `evaluateAccess` with the subject and the action fixed (#1219) — rule 10's
+     * `filter` shape, compiled once and applied to many resources.
+     *
+     * Policies that cannot match this subject or this action are dropped here,
+     * once; the predicate matches resources only, in the same order as
+     * `evaluateAccess` so first-match-wins gives the same answer. No log line
+     * per call: a listing asks this ~18k times, and the per-policy INFO line
+     * `evaluateAccess` writes is right for one decision and wrong for a filter.
+     */
+    compile(userContext: UserContext | undefined, action: string): (pageName: string, attributes?: ResourceAttributes) => EvaluationResult;
+    matchesResource(resources: PolicyResource[] | undefined, pageName: string, attributes?: ResourceAttributes): boolean;
+    /**
+     * Checks if the action matches the policy's actions.
+     *
+     * An action matches if:
+     * - No actions specified (applies to all actions), OR
+     * - Action is in the policy's action list, OR
+     * - Policy includes wildcard '*' (matches all actions)
+     *
+     * @param {string[] | undefined} actions - The actions array from the policy
+     * @param {string} action - The action being performed
+     * @returns {boolean} True if the action is in the policy's list
+     *
+     * @example
+     * const matches = evaluator.matchesAction(
+     *   ['page:read', 'page:edit'],
+     *   'page:read'
+     * );
+     * // matches === true
+     */
+    matchesAction(actions: string[] | undefined, action: string): boolean;
+}
+export default PolicyEvaluator;

package/lib/src/managers/RenderingManager.d.ts

@@ -0,0 +1,358 @@
+/**
+ * RenderingManager - Handles markdown rendering and macro expansion
+ */
+import BaseManager from './BaseManager.js';
+import type MarkupParser from '../parsers/MarkupParser.js';
+import type WikiContext from '../context/WikiContext.js';
+import { WikiEngine } from '../types/WikiEngine.js';
+/**
+ * Table parameters
+ */
+interface TableParams {
+    rowNumber: number;
+    style: string;
+    dataStyle: string;
+    headerStyle: string;
+    evenRowStyle: string;
+    oddRowStyle: string;
+    id?: string;
+    isStriped?: boolean;
+}
+/**
+ * User context
+ */
+interface UserContext {
+    username?: string;
+    userName?: string;
+    displayName?: string;
+    [key: string]: unknown;
+}
+/**
+ * Request information
+ */
+interface RequestInfo {
+    [key: string]: unknown;
+}
+/**
+ * Link graph structure
+ */
+interface LinkGraph {
+    [pageName: string]: string[];
+}
+/**
+ * RenderingManager - Handles markdown rendering and macro expansion
+ *
+ * Similar to JSPWiki's RenderingManager, this manager orchestrates the conversion
+ * of markdown/wiki markup to HTML. It supports both legacy direct markdown rendering
+ * and the advanced MarkupParser with multi-phase processing.
+ *
+ * Key features:
+ * - Pluggable parser system (direct markdown-it vs MarkupParser)
+ * - Wiki link parsing and resolution
+ * - Link graph building for backlinks/orphaned pages
+ * - Plugin and variable expansion integration
+ * - Page name matching with plural support
+ *
+ * @class RenderingManager
+ * @extends BaseManager
+ *
+ * @property {MarkdownConverter|null} converter - markdown-it page converter (#1273)
+ * @property {Object} linkGraph - Graph of page links for backlink analysis
+ * @property {LinkParser} linkParser - Parser for wiki-style links
+ * @property {PageNameMatcher|null} pageNameMatcher - Matcher for page name resolution
+ * @property {Object} renderingConfig - Rendering configuration (parser selection, fallback, etc.)
+ *
+ * @see {@link BaseManager} for base functionality
+ * @see {@link MarkupParser} for advanced parsing
+ *
+ * @example
+ * const renderingManager = engine.getManager('RenderingManager');
+ * const html = await renderingManager.renderPage('# Hello World', { pageName: 'Main' });
+ */
+declare class RenderingManager extends BaseManager {
+    private converter;
+    private linkGraph;
+    private linkParser;
+    private pageNameMatcher;
+    private renderingConfig;
+    private cachedPageNames;
+    /**
+     * Creates a new RenderingManager instance
+     *
+     * @constructor
+     * @param {WikiEngine} engine - The wiki engine instance
+     */
+    constructor(engine: WikiEngine);
+    /**
+     * Initialize the RenderingManager
+     *
+     * Sets up the markdown converter, link parser, and rendering configuration.
+     * Determines whether to use the advanced MarkupParser or the legacy direct converter.
+     *
+     * @async
+     * @param {Object} [config={}] - Configuration object (unused, reads from ConfigurationManager)
+     * @returns {Promise<void>}
+     *
+     * @example
+     * await renderingManager.initialize();
+     * console.log('RenderingManager ready');
+     */
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    /**
+     * Get the MarkupParser instance (for WikiContext integration)
+     *
+     * Returns the advanced MarkupParser if enabled and initialized, or null
+     * if using legacy direct markdown rendering.
+     *
+     * @returns {MarkupParser|null} MarkupParser instance if available and enabled
+     *
+     * @example
+     * const parser = renderingManager.getParser();
+     * if (parser) {
+     *   const html = await parser.parse(content, options);
+     * }
+     */
+    getParser(): MarkupParser | null;
+    /**
+     * Load modular rendering configuration from app-default/custom-config.json
+     *
+     * Reads configuration to determine which parser to use and whether to
+     * enable fallback, performance comparison, and debug logging.
+     *
+     * @private
+     * @returns {void}
+     */
+    loadRenderingConfiguration(): void;
+    /**
+     * Render markdown content to HTML with MarkupParser integration
+     * @param {string} content - Markdown content
+     * @param {string} pageName - Current page name
+     * @param {object} userContext - User context for authentication variables
+     * @param {object} requestInfo - Request information
+     * @returns {Promise<string>} Rendered HTML
+     */
+    renderMarkdown(content: string, pageName: string, userContext?: UserContext | null, requestInfo?: RequestInfo | null): Promise<string>;
+    /**
+     * Whose stores a `[store/Title]` link on this page resolves in (#1457): the
+     * owner of the page the link is written in.
+     *
+     * A private page carries its owner in its name; a public page's owner is its
+     * author. Resolved once per render and never from the reader — rendered HTML
+     * is cached and shared, so anything reader-shaped here would leak.
+     *
+     * The metadata read happens only when the content actually holds a candidate
+     * link, so an ordinary page costs one regex. The read has no caller behind
+     * it, like the link graph's.
+     */
+    private resolvePageOwner;
+    /**
+     * Render content using the advanced MarkupParser system
+     * @param {string} content - Content to render
+     * @param {string} pageName - Page name
+     * @param {object} userContext - User context
+     * @param {object} requestInfo - Request information
+     * @returns {Promise<string>} Rendered HTML
+     */
+    renderWithAdvancedParser(content: string, pageName: string, userContext: UserContext | null, requestInfo: RequestInfo | null): Promise<string>;
+    /**
+     * Render content using the legacy rendering system (backward compatibility)
+     * @param {string} content - Content to render
+     * @param {string} pageName - Page name
+     * @param {object} userContext - User context
+     * @param {object} requestInfo - Request information
+     * @returns {Promise<string>} Rendered HTML
+     */
+    renderWithLegacyParser(content: string, pageName: string, userContext: UserContext | null, requestInfo: RequestInfo | null): Promise<string>;
+    /**
+     * Perform performance comparison between advanced and legacy parsers (modular benchmarking)
+     * @param {string} content - Content that was parsed
+     * @param {string} pageName - Page name
+     * @param {object} userContext - User context
+     * @param {object} requestInfo - Request information
+     * @param {number} advancedTime - Time taken by advanced parser
+     */
+    performPerformanceComparison(content: string, pageName: string, userContext: UserContext | null, requestInfo: RequestInfo | null, advancedTime: number): Promise<void>;
+    /**
+     * Process JSPWiki-style table syntax with styling parameters
+     * @param {string} content - Content with JSPWiki table syntax
+     * @returns {string} Content with processed tables
+     */
+    processJSPWikiTables(content: string): string;
+    /**
+     * Process %%table-striped syntax for theme-based alternating rows
+     * @param {string} content - Content with %%table-striped syntax
+     * @returns {string} Content with processed tables
+     */
+    processTableStripedSyntax(content: string): string;
+    /**
+     * Parse table parameters from JSPWiki Table plugin syntax
+     * @param {string} paramString - Parameter string
+     * @returns {Object} Parsed parameters
+     */
+    parseTableParameters(paramString: string): TableParams;
+    /**
+     * Convert JSPWiki table syntax to markdown table syntax
+     * @param {string} tableContent - JSPWiki table content
+     * @param {Object} params - Table parameters
+     * @returns {string} Markdown table
+     */
+    convertJSPWikiTableToMarkdown(tableContent: string, params: TableParams): string;
+    /**
+     * Post-process rendered HTML tables to apply JSPWiki styling
+     * @param {string} html - Rendered HTML
+     * @returns {string} HTML with styled tables
+     */
+    postProcessTables(html: string): string;
+    /**
+     * Generate styled table HTML with CSS
+     * @param {Object} metadata - Table styling metadata
+     * @returns {string} Styled table opening tag with CSS
+     */
+    generateStyledTable(metadata: TableParams & {
+        id: string;
+        isStriped?: boolean;
+    }): string;
+    /**
+     * Expand macros in content
+     * @param {string} content - Content with macros
+     * @param {string} pageName - Current page name
+     * @param {object} userContext - User context for authentication variables
+     * @returns {string} Content with expanded macros
+     */
+    expandMacros(content: string, pageName: string, userContext?: UserContext | null, requestInfo?: RequestInfo | null): Promise<string>;
+    /**
+     * Expand a single JSPWiki-style system variable
+     * @param {string} variable - The variable name (including $)
+     * @param {string} pageName - Current page name
+     * @param {object} userContext - User context for authentication variables
+     * @returns {string} Expanded value
+     */
+    expandSystemVariable(variable: string, pageName: string, userContext?: UserContext | null): string;
+    /**
+     * Get total pages count
+     * Uses the provider's page cache for an accurate count.
+     * After installation, only counts pages from the main pages directory.
+     * @returns {number} Number of pages
+     */
+    getTotalPagesCount(): number;
+    /**
+     * Get server uptime in seconds
+     * @returns {number} Uptime in seconds
+     */
+    getUptime(): number;
+    /**
+     * Get application version from package.json
+     * @returns {string} Application version
+     */
+    getApplicationVersion(): string;
+    /**
+     * Expand JSPWiki-style system variables (legacy method for compatibility)
+     * @param {string} content - Content with system variables
+     * @returns {string} Content with expanded system variables
+     */
+    expandSystemVariables(content: string): string;
+    /**
+     * Format uptime in human-readable format
+     * @param {number} seconds - Uptime in seconds
+     * @returns {string} Formatted uptime
+     */
+    formatUptime(seconds: number): string;
+    /**
+     * Get the base URL for the application
+     * @returns {string} Base URL
+     */
+    getBaseUrl(): string;
+    /**
+     * Process wiki-style links [PageName]
+     * @param {string} content - Content with wiki links
+     * @returns {Promise<string>} Content with processed links
+     */
+    processWikiLinks(content: string): Promise<string>;
+    /**
+     * Build link graph for referring pages
+     */
+    buildLinkGraph(): Promise<void>;
+    /**
+     * Initialize LinkParser with page names and configuration
+     */
+    initializeLinkParser(): void;
+    /**
+     * Get link graph
+     * @returns {Object} Link graph object
+     */
+    getLinkGraph(): LinkGraph;
+    /**
+     * Rebuild link graph (called after page changes)
+     */
+    rebuildLinkGraph(): Promise<void>;
+    /**
+     * Update link graph for a single page (incremental update)
+     * Much faster than rebuildLinkGraph() for single page saves
+     *
+     * @param {string} pageName - Name of the page that was modified
+     * @param {string} content - New content of the page
+     */
+    updatePageInLinkGraph(pageName: string, content: string): void;
+    /**
+     * Add a page name to the cached list (for new pages)
+     * @param {string} pageName - Name of the new page
+     */
+    addPageToCache(pageName: string): void;
+    /** #1419: see PageManager.isSharedIndexable. Without a PageManager nothing can be sealed. */
+    private isSharedIndexable;
+    /**
+     * Remove a page from the link graph and cached names (for deleted pages)
+     * @param {string} pageName - Name of the deleted page
+     */
+    removePageFromLinkGraph(pageName: string): void;
+    /**
+     * Get pages that refer to a specific page
+     * @param {string} pageName - Target page name
+     * @returns {Array<string>} Array of referring page names
+     * @todo
+     * SHOULD BE using plugins/referringPagesPlugin.js
+     */
+    getReferringPages(pageName: string): string[];
+    /**
+     * Render page preview
+     * @param {string} content - Markdown content
+     * @param {string} pageName - Page name for context
+     * @param {object} userContext - User context for authentication variables
+     * @returns {Promise<string>} Rendered HTML preview
+     */
+    renderPreview(content: string, pageName: string, userContext?: UserContext | null): Promise<string>;
+    /**
+     * Get current username from user context
+     * @param {object} userContext - User context object
+     * @returns {string} Username or "Anonymous"
+     */
+    getUserName(userContext: UserContext | null): string;
+    /**
+     * Get current login status from user context
+     * @param {object} userContext - User context object
+     * @returns {string} Login status description
+     */
+    getLoginStatus(userContext: UserContext | null): string;
+    /**
+     * Render wiki links (JSPWiki-style links) using LinkParser
+     * @param {string} content - Content with wiki links
+     * @returns {string} Content with rendered links
+     */
+    renderWikiLinks(content: string): string;
+    /**
+     * Render plugins (JSPWiki-style plugins)
+     * @param {string} content - Content with plugin syntax
+     * @param {string} pageName - Page name for plugin context
+     * @returns {string} Content with rendered plugins
+     */
+    renderPlugins(content: string, pageName: string): Promise<string>;
+    /**
+     * Converts wiki markup to HTML using the provided WikiContext.
+     * This is the main entry point for the rendering pipeline.
+     * @param {WikiContext} context The context for the rendering operation.
+     * @param {string} content The raw wiki markup to render.
+     * @returns {Promise<string>} The rendered HTML.
+     */
+    textToHTML(context: WikiContext, content: string): Promise<string>;
+}
+export default RenderingManager;