@ankhorage/paradox 0.1.26 → 0.2.0

package/dist/analyze/documentation/validateDocumentationPolicyAsync.js

@@ -0,0 +1,150 @@
+import { access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { DOCUMENTATION_POLICY } from '@ankhorage/policy/documentation';
+import { Node } from 'ts-morph';
+import { getParadoxComment } from '../utils/getParadoxComment.js';
+import { parseParadoxComment } from '../utils/parseParadoxComment.js';
+import { createDocumentationFinding } from './findings.js';
+import { validateReferencesAsync } from './validateReferencesAsync.js';
+/***
+ * Evaluates package documentation evidence against the canonical Ankhorage documentation policy.
+ */
+export async function validateDocumentationPolicyAsync(options) {
+    return [
+        ...validateCommentRules(options.comments),
+        ...validateUsageRules(options.comments),
+        ...(await validateConfigRulesAsync(options.root, options.project)),
+        ...validatePublicApiRules(options.exports),
+        ...(await validateReferencesAsync(options.root, options.project, options.comments, {
+            validateSeeUrlAsync: options.validateSeeUrlAsync,
+        })),
+    ];
+}
+/***
+ * Validates generic comment syntax rules shared by all documentation contexts.
+ */
+function validateCommentRules(comments) {
+    return comments.flatMap((comment) => {
+        const unsupported = comment.parsed.unsupportedTags.map((tag) => finding('documentation.comment.tag.unsupported', `Unsupported Paradox tag: @${tag}`, comment));
+        const code = comment.parsed.hasCodeBlock
+            ? [
+                finding('documentation.comment.code-block', 'Paradox comments must not contain code blocks.', comment),
+            ]
+            : [];
+        const configLocation = comment.parsed.isConfig && comment.sourcePath !== DOCUMENTATION_POLICY.config.path
+            ? [
+                finding('documentation.config.location', `@config is allowed only in ${DOCUMENTATION_POLICY.config.path}.`, comment),
+            ]
+            : [];
+        return [...unsupported, ...code, ...configLocation];
+    });
+}
+/***
+ * Validates canonical usage locations and the single README-promoted programmatic example.
+ */
+function validateUsageRules(comments) {
+    const usageComments = comments.filter((comment) => comment.parsed.isUsage);
+    const findings = usageComments.flatMap((comment) => validateUsageComment(comment));
+    const readmeExamples = usageComments.filter((comment) => isBelow(comment.sourcePath, DOCUMENTATION_POLICY.paths.examplesRoot) &&
+        comment.parsed.isReadme);
+    if (readmeExamples.length !== DOCUMENTATION_POLICY.readmeUsage.exactCount) {
+        findings.push(createDocumentationFinding('documentation.usage.readme.unique', `Expected exactly one @usage + @readme example; found ${readmeExamples.length}.`));
+    }
+    for (const comment of readmeExamples) {
+        if (!hasExactlyOneRequiredTag(comment, DOCUMENTATION_POLICY.readmeUsage.requiredTags) ||
+            comment.parsed.description === null) {
+            findings.push(finding('documentation.usage.readme.metadata', 'README usage requires non-empty @title and prose.', comment));
+        }
+    }
+    return findings;
+}
+/***
+ * Validates one usage comment location and forbidden CLI README promotion.
+ */
+function validateUsageComment(comment) {
+    const allowed = DOCUMENTATION_POLICY.paths.usageRoots.some((root) => isBelow(comment.sourcePath, root));
+    const location = allowed
+        ? []
+        : [
+            finding('documentation.usage.location', '@usage is allowed only below examples/** or src/cli/**.', comment),
+        ];
+    const cliReadme = isBelow(comment.sourcePath, DOCUMENTATION_POLICY.paths.cliRoot) && comment.parsed.isReadme
+        ? [
+            finding('documentation.usage.readme.cli', '@usage + @readme is not allowed below src/cli/**.', comment),
+        ]
+        : [];
+    return [...location, ...cliReadme];
+}
+/***
+ * Validates the canonical configuration file and its one README configuration root.
+ */
+async function validateConfigRulesAsync(root, project) {
+    const configPath = join(root, DOCUMENTATION_POLICY.config.path);
+    if (!(await fileExistsAsync(configPath))) {
+        return [
+            createDocumentationFinding('documentation.config.file', `Missing canonical config schema: ${DOCUMENTATION_POLICY.config.path}`),
+        ];
+    }
+    const sourceFile = project.getSourceFile(configPath) ?? project.addSourceFileAtPath(configPath);
+    const roots = sourceFile.getStatements().flatMap((statement) => {
+        if (!Node.isInterfaceDeclaration(statement) && !Node.isTypeAliasDeclaration(statement)) {
+            return [];
+        }
+        const raw = getParadoxComment(statement);
+        if (raw === null)
+            return [];
+        const parsed = parseParadoxComment(raw);
+        return parsed.isConfig && parsed.isReadme ? [{ statement, parsed }] : [];
+    });
+    const findings = [];
+    if (roots.length !== DOCUMENTATION_POLICY.config.exactCount) {
+        findings.push(createDocumentationFinding('documentation.config.readme.unique', `Expected exactly one @config + @readme root in ${DOCUMENTATION_POLICY.config.path}; found ${roots.length}.`, DOCUMENTATION_POLICY.config.path));
+    }
+    for (const rootEntry of roots) {
+        if (!hasExactlyOneRequiredTag(rootEntry, DOCUMENTATION_POLICY.config.requiredTags) ||
+            rootEntry.parsed.description === null) {
+            findings.push(createDocumentationFinding('documentation.config.readme.metadata', 'README configuration requires non-empty @title and prose.', DOCUMENTATION_POLICY.config.path, rootEntry.statement.getStartLineNumber()));
+        }
+    }
+    return findings;
+}
+/***
+ * Warns when a public callable export has no Paradox description.
+ */
+function validatePublicApiRules(exports) {
+    return exports.flatMap((entry) => entry.signatures.length > 0 && entry.description === null
+        ? [
+            createDocumentationFinding('documentation.public-function.description', `Public function ${entry.name} has no Paradox description.`, entry.sourceLocation.filePath, entry.sourceLocation.line),
+        ]
+        : []);
+}
+/***
+ * Checks that each policy-required tag appears exactly once on one parsed documentation item.
+ */
+function hasExactlyOneRequiredTag(entry, requiredTags) {
+    return requiredTags.every((name) => entry.parsed.tags.filter((tag) => tag.name === name).length === 1);
+}
+/***
+ * Creates a finding at one collected comment location.
+ */
+function finding(ruleId, message, comment) {
+    return createDocumentationFinding(ruleId, message, comment.sourcePath, comment.line);
+}
+/***
+ * Checks whether a source path is contained in one canonical root.
+ */
+function isBelow(sourcePath, root) {
+    return sourcePath === root || sourcePath.startsWith(`${root}/`);
+}
+/***
+ * Checks whether a required canonical file exists.
+ */
+async function fileExistsAsync(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/analyze/documentation/validateReferencesAsync.d.ts

@@ -0,0 +1,11 @@
+import { type Project } from 'ts-morph';
+import type { AnalysisDocumentationFinding } from '../types.js';
+import type { CollectedDocumentationComment } from './collectDocumentationCommentsAsync.js';
+type SeeUrlValidator = (url: string) => Promise<unknown>;
+/***
+ * Validates external and executable references carried by documentation comments.
+ */
+export declare function validateReferencesAsync(root: string, project: Project, comments: readonly CollectedDocumentationComment[], options?: {
+    validateSeeUrlAsync?: SeeUrlValidator;
+}): Promise<AnalysisDocumentationFinding[]>;
+export {};

package/dist/analyze/documentation/validateReferencesAsync.js

@@ -0,0 +1,148 @@
+import { access } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { DOCUMENTATION_POLICY } from '@ankhorage/policy/documentation';
+import { validatePublicHttpsUrlAsync } from '@ankhorage/utility/node/http';
+import { Node } from 'ts-morph';
+import { createDocumentationFinding } from './findings.js';
+/***
+ * Validates external and executable references carried by documentation comments.
+ */
+export async function validateReferencesAsync(root, project, comments, options = {}) {
+    const validateSeeUrlAsync = options.validateSeeUrlAsync ?? validatePublicHttpsUrlAsync;
+    const findings = await Promise.all(comments.map(async (comment) => [
+        ...(await validateSeeReferencesAsync(comment, validateSeeUrlAsync)),
+        ...(await validateSecurityReferencesAsync(root, project, comment)),
+    ]));
+    return findings.flat();
+}
+/***
+ * Validates every @see value through syntax policy and the hardened public HTTPS utility.
+ */
+async function validateSeeReferencesAsync(comment, validateSeeUrlAsync) {
+    const seeTags = comment.parsed.tags.filter((tag) => tag.name === 'see');
+    const findings = await Promise.all(seeTags.map(async (tag) => {
+        const url = parseSeeUrl(tag.value);
+        if (url === null) {
+            return [
+                referenceFinding('documentation.see.value', '@see requires a public HTTPS URL without credentials.', comment),
+            ];
+        }
+        try {
+            await validateSeeUrlAsync(url);
+            return [];
+        }
+        catch (error) {
+            return [
+                referenceFinding('documentation.see.reachable', `@see target is not safely reachable: ${readErrorMessage(error)}`, comment),
+            ];
+        }
+    }));
+    return findings.flat();
+}
+/***
+ * Parses one @see value according to the policy-owned URL syntax contract.
+ */
+function parseSeeUrl(value) {
+    if (value === null)
+        return null;
+    try {
+        const url = new URL(value);
+        if (url.protocol !== DOCUMENTATION_POLICY.see.protocol)
+            return null;
+        if (url.username || url.password || url.hostname.length === 0)
+            return null;
+        return url.toString();
+    }
+    catch {
+        return null;
+    }
+}
+/***
+ * Validates every @security reference against one exact colocated executable test.
+ */
+async function validateSecurityReferencesAsync(root, project, comment) {
+    const securityTags = comment.parsed.tags.filter((tag) => tag.name === 'security');
+    return (await Promise.all(securityTags.map((tag) => validateSecurityReferenceAsync(root, project, comment, tag.value)))).flat();
+}
+/***
+ * Resolves one colocated security test reference and requires exactly one matching test declaration.
+ */
+async function validateSecurityReferenceAsync(root, project, comment, value) {
+    const reference = parseSecurityReference(value);
+    if (reference === null) {
+        return [securityFinding('Invalid @security test reference.', comment)];
+    }
+    const testPath = join(root, dirname(comment.sourcePath), reference.fileName);
+    if (!(await fileExistsAsync(testPath))) {
+        return [securityFinding(`Missing colocated security test: ${reference.fileName}`, comment)];
+    }
+    const sourceFile = project.getSourceFile(testPath) ?? project.addSourceFileAtPath(testPath);
+    const matches = sourceFile
+        .getDescendants()
+        .filter((node) => isNamedTestCall(node, reference.testName));
+    return matches.length === 1
+        ? []
+        : [
+            securityFinding(`Expected exactly one test named "${reference.testName}" in ${reference.fileName}; found ${matches.length}.`, comment),
+        ];
+}
+/***
+ * Parses a same-directory test filename and exact test name from an @security value.
+ */
+function parseSecurityReference(value) {
+    if (value === null)
+        return null;
+    const separator = value.indexOf('#');
+    if (separator <= 0 || separator === value.length - 1)
+        return null;
+    const fileName = value.slice(0, separator).trim();
+    const testName = value.slice(separator + 1).trim();
+    if (basename(fileName) !== fileName || !/\.(?:test|spec)\.[cm]?[jt]sx?$/.test(fileName)) {
+        return null;
+    }
+    return testName.length > 0 ? { fileName, testName } : null;
+}
+/***
+ * Checks whether a ts-morph node is test()/it() with the exact static string name.
+ */
+function isNamedTestCall(node, expectedName) {
+    if (!Node.isCallExpression(node))
+        return false;
+    const callee = node.getExpression().getText();
+    if (callee !== 'test' && callee !== 'it')
+        return false;
+    const [name] = node.getArguments();
+    if (!Node.isStringLiteral(name) && !Node.isNoSubstitutionTemplateLiteral(name))
+        return false;
+    return name.getLiteralText() === expectedName;
+}
+/***
+ * Creates the canonical security-reference finding at a comment location.
+ */
+function securityFinding(message, comment) {
+    return referenceFinding('documentation.security.reference', message, comment);
+}
+/***
+ * Creates a reference finding at the owning comment location.
+ */
+function referenceFinding(ruleId, message, comment) {
+    return createDocumentationFinding(ruleId, message, comment.sourcePath, comment.line);
+}
+/***
+ * Checks whether a referenced test file exists.
+ */
+async function fileExistsAsync(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/***
+ * Converts an unknown thrown value into a stable diagnostic string.
+ */
+function readErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/analyze/exports.d.ts

@@ -4,7 +4,11 @@ interface AnalyzeExportsResult {
     exports: AnalysisExport[];
     config: {
         exportName: string;
+        title: string | null;
+        description: string | null;
         isReadme: boolean;
+        see: string[];
+        security: string[];
     } | null;
 }
 /***

package/dist/analyze/exports.js

@@ -16,16 +16,19 @@ export function analyzeExports(project, options) {
         for (const symbol of exported) {
             const resolved = resolveExportSymbol(symbol);
             const decl = getFirstDeclaration(resolved.getDeclarations());
-            if (decl === null) {
+            if (decl === null)
                 continue;
-            }
             const rawComment = getParadoxComment(decl);
             const parsed = rawComment ? parseParadoxComment(rawComment) : createEmptyMetadata();
             const name = resolved.getName();
             if (parsed.isConfig) {
                 config = {
                     exportName: name,
+                    title: parsed.title,
+                    description: parsed.description,
                     isReadme: parsed.isReadme,
+                    see: parsed.see,
+                    security: parsed.security,
                 };
             }
             const metadata = getExportMetadata({
@@ -39,9 +42,11 @@ export function analyzeExports(project, options) {
             exportsByName.set(name, existing
                 ? {
                     ...existing,
+                    title: existing.title ?? parsed.title,
                     description: existing.description ?? parsed.description,
                     isReadme: existing.isReadme || parsed.isReadme,
-                    examples: existing.examples.length > 0 ? existing.examples : parsed.examples,
+                    see: uniqueSorted([...existing.see, ...parsed.see]),
+                    security: uniqueSorted([...existing.security, ...parsed.security]),
                     exportPaths: uniqueSorted([...existing.exportPaths, ...metadata.exportPaths]),
                     relatedSymbols: uniqueSorted([
                         ...existing.relatedSymbols,
@@ -56,9 +61,11 @@ export function analyzeExports(project, options) {
                 : {
                     name,
                     node: decl,
+                    title: parsed.title,
                     description: parsed.description,
                     isReadme: parsed.isReadme,
-                    examples: parsed.examples,
+                    see: parsed.see,
+                    security: parsed.security,
                     kind: inferKind(decl),
                     ...metadata,
                 });
@@ -117,10 +124,10 @@ function toPosixPath(path) {
 function createEmptyMetadata() {
     return {
         description: null,
+        title: null,
         isConfig: false,
         isReadme: false,
-        examples: [],
-        params: {},
-        returns: null,
+        see: [],
+        security: [],
     };
 }

package/dist/analyze/readmeConfig.d.ts

@@ -1,12 +1,10 @@
 export interface AnalysisReadmeConfig {
-    description: string | null;
     language: string;
     code: string;
     sourcePath: string;
 }
 /***
- * Collects a README configuration example from the actual Paradox config file when its
- * leading Paradox comment is marked with both @config and @readme.
+ * Collects the concrete Paradox configuration instance as a README configuration example.
  */
 export declare function analyzeReadmeConfig(options: {
     root: string;

package/dist/analyze/readmeConfig.js

@@ -1,36 +1,22 @@
 import { readFile } from 'node:fs/promises';
 import { extname, relative } from 'node:path';
-import { getLeadingParadoxComment } from './utils/getLeadingParadoxComment.js';
 /***
- * Collects a README configuration example from the actual Paradox config file when its
- * leading Paradox comment is marked with both @config and @readme.
+ * Collects the concrete Paradox configuration instance as a README configuration example.
  */
 export async function analyzeReadmeConfig(options) {
     if (options.configFilePath === null)
         return null;
     const source = await readFile(options.configFilePath, 'utf-8');
-    const comment = getLeadingParadoxComment(source);
-    if (comment === null)
-        return null;
-    if (!comment.parsed.isConfig || !comment.parsed.isReadme)
-        return null;
     const sourcePath = toPosixPath(relative(options.root, options.configFilePath));
     return {
-        description: comment.parsed.description,
         language: getLanguage(sourcePath),
-        code: removeRange(source, comment.start, comment.end).trim(),
+        code: source.trim(),
         sourcePath,
     };
 }
-function removeRange(source, start, end) {
-    const before = source.slice(0, start).trimEnd();
-    const after = source.slice(end).trimStart();
-    if (before.length === 0)
-        return after;
-    if (after.length === 0)
-        return before;
-    return `${before}\n\n${after}`;
-}
+/***
+ * Returns the Markdown fence language for a configuration source path.
+ */
 function getLanguage(sourcePath) {
     const extension = extname(sourcePath).toLowerCase();
     if (extension === '.ts')
@@ -39,6 +25,9 @@ function getLanguage(sourcePath) {
         return 'js';
     return '';
 }
+/***
+ * Normalizes filesystem separators for stable documentation paths.
+ */
 function toPosixPath(path) {
     return path.replaceAll('\\', '/');
 }

package/dist/analyze/readmeUsage.d.ts

@@ -1,14 +1,11 @@
-export interface AnalysisReadmeUsage {
-    title: string | null;
-    description: string | null;
-    language: string;
-    code: string;
-    sourcePath: string;
-}
+import type { AnalysisUsageEntry } from './types.js';
 /***
- * Collects README usage examples from configured real source files.
+ * Collects every canonical usage declaration from examples and CLI source roots.
  */
 export declare function analyzeReadmeUsage(options: {
     root: string;
-    entrypoints: readonly string[];
-}): Promise<AnalysisReadmeUsage[]>;
+}): Promise<AnalysisUsageEntry[]>;
+/***
+ * Counts real example directories directly below the canonical examples root.
+ */
+export declare function countExampleDirectoriesAsync(root: string): Promise<number>;

package/dist/analyze/readmeUsage.js

@@ -1,60 +1,108 @@
-import { readFile } from 'node:fs/promises';
-import { extname, isAbsolute, join, relative } from 'node:path';
+import { readdir } from 'node:fs/promises';
+import { extname, join, relative } from 'node:path';
+import { DOCUMENTATION_POLICY } from '@ankhorage/policy/documentation';
+import { Project } from 'ts-morph';
+import { getParadoxComment } from './utils/getParadoxComment.js';
 import { parseParadoxComment } from './utils/parseParadoxComment.js';
-const USAGE_TAG = `${String.fromCharCode(64)}usage`;
+const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
 /***
- * Collects README usage examples from configured real source files.
+ * Collects every canonical usage declaration from examples and CLI source roots.
  */
 export async function analyzeReadmeUsage(options) {
-    const entries = await Promise.all(options.entrypoints.map(async (entrypoint) => analyzeUsageEntrypoint(options.root, entrypoint)));
-    return entries.flat().sort((left, right) => left.sourcePath.localeCompare(right.sourcePath));
+    const project = new Project({ skipAddingFilesFromTsConfig: true });
+    const files = (await Promise.all(DOCUMENTATION_POLICY.paths.usageRoots.map((usageRoot) => collectSourceFilesAsync(join(options.root, usageRoot)))))
+        .flat()
+        .sort((left, right) => left.localeCompare(right));
+    return files.flatMap((filePath) => analyzeUsageFile(options.root, project, filePath));
 }
-async function analyzeUsageEntrypoint(root, entrypoint) {
-    const absolutePath = isAbsolute(entrypoint) ? entrypoint : join(root, entrypoint);
-    const source = await readFile(absolutePath, 'utf-8');
-    const sourcePath = toPosixPath(relative(root, absolutePath));
-    const matches = findUsageComments(source);
-    return matches.map((match) => {
-        const parsed = parseParadoxComment(match.comment);
-        return {
-            title: getUsageTitle(parsed.description, sourcePath),
-            description: parsed.description,
-            language: getLanguage(sourcePath),
-            code: removeRange(source, match.start, match.end).trim(),
-            sourcePath,
-        };
+/***
+ * Collects supported source files recursively below one canonical usage root.
+ */
+async function collectSourceFilesAsync(root) {
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isMissingPathError(error))
+            return [];
+        throw error;
+    }
+    const nested = await Promise.all(entries.map(async (entry) => {
+        const path = join(root, entry.name);
+        if (entry.isDirectory())
+            return collectSourceFilesAsync(path);
+        return entry.isFile() && SOURCE_EXTENSIONS.has(extname(entry.name)) ? [path] : [];
+    }));
+    return nested.flat();
+}
+/***
+ * Extracts usage-marked top-level statements from one real source file.
+ */
+function analyzeUsageFile(root, project, filePath) {
+    const sourceFile = project.getSourceFile(filePath) ?? project.addSourceFileAtPath(filePath);
+    const sourcePath = toPosixPath(relative(root, filePath));
+    return sourceFile.getStatements().flatMap((statement) => {
+        const comment = getParadoxComment(statement);
+        if (comment === null)
+            return [];
+        const parsed = parseParadoxComment(comment);
+        if (!parsed.isUsage)
+            return [];
+        return [
+            {
+                area: sourcePath.startsWith(`${DOCUMENTATION_POLICY.paths.examplesRoot}/`)
+                    ? 'examples'
+                    : 'cli',
+                title: parsed.title ?? deriveUsageTitle(sourcePath),
+                description: parsed.description,
+                language: getLanguage(sourcePath),
+                code: getStatementCode(statement),
+                sourcePath,
+                isReadme: parsed.isReadme,
+                see: parsed.see,
+                security: parsed.security,
+            },
+        ];
     });
 }
-function findUsageComments(source) {
-    const matches = [];
-    const pattern = /\/\*\*\*[\s\S]*?\*\//g;
-    for (const match of source.matchAll(pattern)) {
-        const [comment] = match;
-        if (!comment.includes(USAGE_TAG))
-            continue;
-        matches.push({
-            comment,
-            start: match.index,
-            end: match.index + comment.length,
-        });
-    }
-    return matches;
+/***
+ * Returns the exact source statement owned by a usage comment.
+ */
+function getStatementCode(statement) {
+    return statement.getText().trim();
 }
-function removeRange(source, start, end) {
-    const before = source.slice(0, start).trimEnd();
-    const after = source.slice(end).trimStart();
-    if (before.length === 0)
-        return after;
-    if (after.length === 0)
-        return before;
-    return `${before}\n\n${after}`;
+/***
+ * Derives a deterministic title from the canonical example or CLI structure.
+ */
+function deriveUsageTitle(sourcePath) {
+    const parts = sourcePath.split('/');
+    if (parts[0] === DOCUMENTATION_POLICY.paths.examplesRoot) {
+        return titleCase(parts[1] ?? 'usage');
+    }
+    if (sourcePath === `${DOCUMENTATION_POLICY.paths.cliRoot}/index.ts`) {
+        return 'CLI';
+    }
+    const commandsIndex = parts.indexOf('commands');
+    const commandParts = commandsIndex === -1 ? [parts.at(-1) ?? 'cli'] : parts.slice(commandsIndex + 1);
+    return commandParts
+        .map((part) => part.replace(/\.[^.]+$/, ''))
+        .map(titleCase)
+        .join(' ');
 }
-function getUsageTitle(description, sourcePath) {
-    if (description === null)
-        return sourcePath;
-    const [firstLine = sourcePath] = description.split('\n');
-    return firstLine.trim() || sourcePath;
+/***
+ * Converts a kebab-case structural segment into presentation words.
+ */
+function titleCase(value) {
+    return value
+        .split('-')
+        .filter((word) => word.length > 0)
+        .map((word) => `${word.charAt(0).toUpperCase()}${word.slice(1)}`)
+        .join(' ');
 }
+/***
+ * Returns the Markdown fence language for a usage source path.
+ */
 function getLanguage(sourcePath) {
     const extension = extname(sourcePath).toLowerCase();
     if (extension === '.tsx')
@@ -63,10 +111,38 @@ function getLanguage(sourcePath) {
         return 'ts';
     if (extension === '.jsx')
         return 'jsx';
-    if (extension === '.js')
+    if (extension === '.js' || extension === '.mjs' || extension === '.cjs')
         return 'js';
     return '';
 }
+/***
+ * Counts real example directories directly below the canonical examples root.
+ */
+export async function countExampleDirectoriesAsync(root) {
+    try {
+        const entries = await readdir(join(root, DOCUMENTATION_POLICY.paths.examplesRoot), {
+            withFileTypes: true,
+        });
+        return entries.filter((entry) => entry.isDirectory()).length;
+    }
+    catch (error) {
+        if (isMissingPathError(error))
+            return 0;
+        throw error;
+    }
+}
+/***
+ * Checks whether a filesystem error reports a missing path.
+ */
+function isMissingPathError(error) {
+    return (error instanceof Error &&
+        'code' in error &&
+        typeof error.code === 'string' &&
+        error.code === 'ENOENT');
+}
+/***
+ * Normalizes filesystem separators for stable documentation paths.
+ */
 function toPosixPath(path) {
     return path.replaceAll('\\', '/');
 }