@breadstone-infrastructure/nx-tasks 0.0.230 → 0.0.232

package/utils/markdown-processing.js

@@ -0,0 +1,186 @@
+"use strict";
+/**
+ * Shared Markdown post-processing utilities for TypeDoc-generated documentation.
+ * All functions are stateless and operate on individual files.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeFrontmatter = normalizeFrontmatter;
+exports.rewriteLinks = rewriteLinks;
+exports.stripPackageBackLink = stripPackageBackLink;
+exports.resolveInlineLinks = resolveInlineLinks;
+exports.escapeAngleBrackets = escapeAngleBrackets;
+exports.countMarkdownFiles = countMarkdownFiles;
+exports.processMarkdownFiles = processMarkdownFiles;
+// gray-matter is CJS — use import = require() to avoid ESM interop issues in NX JIT
+const matter = require("gray-matter");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const valid_html_tags_1 = require("./valid-html-tags");
+/**
+ * Ensures the Markdown file has valid frontmatter with a title.
+ * Optionally marks the file as auto-generated.
+ */
+function normalizeFrontmatter(filePath, options = {}) {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const parsed = matter(content);
+    if (!parsed.data['title'] && parsed.content) {
+        const h1Match = parsed.content.match(/^#\s+(.+)$/m);
+        if (h1Match) {
+            parsed.data['title'] = h1Match[1].trim();
+        }
+    }
+    if (options.generated) {
+        parsed.data['generated'] = true;
+        parsed.data['editUrl'] = false;
+    }
+    const updated = matter.stringify(parsed.content, parsed.data);
+    fs.writeFileSync(filePath, updated, 'utf-8');
+}
+/**
+ * Rewrites `.md` extensions to clean URLs and README links to parent directory.
+ * Required for VitePress compatibility.
+ */
+function rewriteLinks(filePath) {
+    let content = fs.readFileSync(filePath, 'utf-8');
+    content = content.replace(/\]\(([^)]+?)\.md(#[^)]*?)?\)/g, (match, linkPath, anchor) => {
+        if (linkPath.startsWith('http://') || linkPath.startsWith('https://')) {
+            return match;
+        }
+        return `](${linkPath}${anchor ?? ''})`;
+    });
+    content = content.replace(/\]\((?:\.\/)?README(#[^)]*?)?\)/g, (_match, anchor) => `](../${anchor ?? ''})`);
+    fs.writeFileSync(filePath, content, 'utf-8');
+}
+/**
+ * Removes the TypeDoc-generated package back-link and separator at the top.
+ * Matches any scoped package pattern: `[**@scope/package-name**](../)`
+ */
+function stripPackageBackLink(filePath) {
+    let content = fs.readFileSync(filePath, 'utf-8');
+    content = content.replace(/\[?\[?\*\*@[^*]+\*\*\]?\(\.\.\/?\)\]?\s*\n+\*{3}\s*\n+/g, '');
+    fs.writeFileSync(filePath, content, 'utf-8');
+}
+/**
+ * Resolves unresolved `{@link Foo}` TSDoc references in inline code.
+ * Converts `{@link Foo}` → `Foo`.
+ */
+function resolveInlineLinks(filePath) {
+    let content = fs.readFileSync(filePath, 'utf-8');
+    content = content.replace(/\{@link\s+([^}]+)\}/g, '$1');
+    fs.writeFileSync(filePath, content, 'utf-8');
+}
+/**
+ * Escapes angle brackets in TypeDoc-generated Markdown that Vue's compiler
+ * would misinterpret as HTML/component tags (e.g. `Promise<boolean>`).
+ * Only processes lines outside fenced code blocks and inline code spans.
+ */
+function escapeAngleBrackets(filePath) {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n');
+    let insideCodeFence = false;
+    const result = [];
+    for (const line of lines) {
+        if (/^```/.test(line.trimStart())) {
+            insideCodeFence = !insideCodeFence;
+            result.push(line);
+            continue;
+        }
+        if (insideCodeFence) {
+            result.push(line);
+            continue;
+        }
+        const segments = line.split(/(`[^`]*`)/g);
+        const escaped = segments
+            .map((segment, index) => {
+            if (index % 2 === 1)
+                return segment;
+            return segment.replace(/(?<!\\)<(\/?[A-Za-z][A-Za-z0-9., |_[\]]*?)(?<!\\)>/g, (_match, inner) => {
+                const tagName = inner
+                    .replace(/^\//, '')
+                    .split(/[\s,.[|]/)[0]
+                    .toLowerCase();
+                if (valid_html_tags_1.VALID_HTML_TAGS.has(tagName))
+                    return _match;
+                return `\\<${inner}\\>`;
+            });
+        })
+            .join('');
+        result.push(escaped);
+    }
+    const updated = result.join('\n');
+    if (updated !== content) {
+        fs.writeFileSync(filePath, updated, 'utf-8');
+    }
+}
+/**
+ * Recursively counts Markdown files in a directory.
+ */
+function countMarkdownFiles(dir) {
+    if (!fs.existsSync(dir))
+        return 0;
+    let count = 0;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+            count += countMarkdownFiles(path.join(dir, entry.name));
+        }
+        else if (entry.name.endsWith('.md')) {
+            count++;
+        }
+    }
+    return count;
+}
+/**
+ * Recursively processes all Markdown files in a directory,
+ * applying normalization, link rewriting, and escaping.
+ */
+function processMarkdownFiles(dir, options = {}) {
+    if (!fs.existsSync(dir))
+        return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            processMarkdownFiles(fullPath, options);
+        }
+        else if (entry.name.endsWith('.md')) {
+            normalizeFrontmatter(fullPath, options);
+            rewriteLinks(fullPath);
+            if (options.generated) {
+                escapeAngleBrackets(fullPath);
+            }
+        }
+    }
+}
+//# sourceMappingURL=markdown-processing.js.map

package/utils/markdown-processing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-processing.js","sourceRoot":"","sources":["../../src/utils/markdown-processing.ts"],"names":[],"mappings":"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"}

package/utils/valid-html-tags.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Comprehensive set of valid HTML tags that should not be escaped
+ * when processing TypeDoc-generated Markdown for VitePress.
+ */
+export declare const VALID_HTML_TAGS: Set<string>;
+//# sourceMappingURL=valid-html-tags.d.ts.map

package/utils/valid-html-tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"valid-html-tags.d.ts","sourceRoot":"","sources":["../../src/utils/valid-html-tags.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,eAAe,aA0E1B,CAAC"}

package/utils/valid-html-tags.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VALID_HTML_TAGS = void 0;
+/**
+ * Comprehensive set of valid HTML tags that should not be escaped
+ * when processing TypeDoc-generated Markdown for VitePress.
+ */
+exports.VALID_HTML_TAGS = new Set([
+    'a',
+    'abbr',
+    'article',
+    'aside',
+    'b',
+    'blockquote',
+    'body',
+    'br',
+    'button',
+    'code',
+    'dd',
+    'del',
+    'details',
+    'div',
+    'dl',
+    'dt',
+    'em',
+    'fieldset',
+    'figcaption',
+    'figure',
+    'footer',
+    'form',
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'h6',
+    'head',
+    'header',
+    'hr',
+    'html',
+    'i',
+    'img',
+    'input',
+    'kbd',
+    'label',
+    'legend',
+    'li',
+    'link',
+    'main',
+    'mark',
+    'meta',
+    'nav',
+    'ol',
+    'option',
+    'p',
+    'picture',
+    'pre',
+    'ruby',
+    's',
+    'script',
+    'section',
+    'select',
+    'small',
+    'source',
+    'span',
+    'strong',
+    'style',
+    'sub',
+    'summary',
+    'sup',
+    'table',
+    'tbody',
+    'td',
+    'textarea',
+    'tfoot',
+    'th',
+    'thead',
+    'tr',
+    'u',
+    'ul',
+    'video',
+]);
+//# sourceMappingURL=valid-html-tags.js.map

package/utils/valid-html-tags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"valid-html-tags.js","sourceRoot":"","sources":["../../src/utils/valid-html-tags.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACU,QAAA,eAAe,GAAG,IAAI,GAAG,CAAS;IAC7C,GAAG;IACH,MAAM;IACN,SAAS;IACT,OAAO;IACP,GAAG;IACH,YAAY;IACZ,MAAM;IACN,IAAI;IACJ,QAAQ;IACR,MAAM;IACN,IAAI;IACJ,KAAK;IACL,SAAS;IACT,KAAK;IACL,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,UAAU;IACV,YAAY;IACZ,QAAQ;IACR,QAAQ;IACR,MAAM;IACN,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,MAAM;IACN,QAAQ;IACR,IAAI;IACJ,MAAM;IACN,GAAG;IACH,KAAK;IACL,OAAO;IACP,KAAK;IACL,OAAO;IACP,QAAQ;IACR,IAAI;IACJ,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,KAAK;IACL,IAAI;IACJ,QAAQ;IACR,GAAG;IACH,SAAS;IACT,KAAK;IACL,MAAM;IACN,GAAG;IACH,QAAQ;IACR,SAAS;IACT,QAAQ;IACR,OAAO;IACP,QAAQ;IACR,MAAM;IACN,QAAQ;IACR,OAAO;IACP,KAAK;IACL,SAAS;IACT,KAAK;IACL,OAAO;IACP,OAAO;IACP,IAAI;IACJ,UAAU;IACV,OAAO;IACP,IAAI;IACJ,OAAO;IACP,IAAI;IACJ,GAAG;IACH,IAAI;IACJ,OAAO;CACR,CAAC,CAAC"}