honkit 3.6.21

package/lib/models/summary.js

@@ -0,0 +1,199 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const is_1 = __importDefault(require("is"));
+const immutable_1 = __importDefault(require("immutable"));
+const error_1 = __importDefault(require("../utils/error"));
+const location_1 = __importDefault(require("../utils/location"));
+const file_1 = __importDefault(require("./file"));
+const summaryPart_1 = __importDefault(require("./summaryPart"));
+const summaryArticle_1 = __importDefault(require("./summaryArticle"));
+const parsers_1 = __importDefault(require("../parsers"));
+class Summary extends immutable_1.default.Record({
+    file: new file_1.default(),
+    parts: immutable_1.default.List(),
+}, "Summary") {
+    getFile() {
+        return this.get("file");
+    }
+    getParts() {
+        return this.get("parts");
+    }
+    /**
+     Return a part by its index
+     */
+    getPart(i) {
+        const parts = this.getParts();
+        return parts.get(i);
+    }
+    /**
+     Return an article using an iterator to find it.
+     if "partIter" is set, it can also return a Part.
+
+     @param {Function} iter
+     @param {Function} [partIter]
+     @return {Article|Part}
+     */
+    getArticle(iter, partIter) {
+        const parts = this.getParts();
+        return parts.reduce((result, part) => {
+            if (result)
+                return result;
+            if (partIter && partIter(part))
+                return part;
+            return summaryArticle_1.default.findArticle(part, iter);
+        }, null);
+    }
+    /**
+     Return a part/article by its level
+
+     @param {string} level
+     @return {Article|Part}
+     */
+    getByLevel(level) {
+        function iterByLevel(article) {
+            return article.getLevel() === level;
+        }
+        return this.getArticle(iterByLevel, iterByLevel);
+    }
+    /**
+     Return an article by its path
+
+     @param {string} filePath
+     @return {Article}
+     */
+    getByPath(filePath) {
+        return this.getArticle((article) => {
+            const articlePath = article.getPath();
+            return articlePath && location_1.default.areIdenticalPaths(articlePath, filePath);
+        });
+    }
+    /**
+     Return the first article
+
+     @return {Article}
+     */
+    getFirstArticle() {
+        return this.getArticle((article) => {
+            return true;
+        });
+    }
+    /**
+     Return next article of an article
+
+     */
+    getNextArticle(current) {
+        const level = typeof current === "string" ? current : current.getLevel();
+        let wasPrev = false;
+        return this.getArticle((article) => {
+            if (wasPrev && !article.hasAnchor()) {
+                return true;
+            }
+            if (!wasPrev) {
+                wasPrev = article.getLevel() === level;
+            }
+            return false;
+        });
+    }
+    /**
+     Return previous article of an article
+
+     @param {Article} current
+     @return {Article}
+     */
+    getPrevArticle(current) {
+        const level = is_1.default.string(current) ? current : current.getLevel();
+        let prev = undefined;
+        this.getArticle((article) => {
+            if (article.getLevel() == level) {
+                return true;
+            }
+            if (!article.hasAnchor()) {
+                prev = article;
+            }
+            return false;
+        });
+        return prev;
+    }
+    /**
+     Return the parent article, or parent part of an article
+
+     @param {String|Article} current
+     @return {Article|Part|Null}
+     */
+    getParent(level) {
+        // Coerce to level
+        level = is_1.default.string(level) ? level : level.getLevel();
+        // Get parent level
+        const parentLevel = getParentLevel(level);
+        if (!parentLevel) {
+            return null;
+        }
+        // Get parent of the position
+        const parentArticle = this.getByLevel(parentLevel);
+        return parentArticle || null;
+    }
+    /**
+     Render summary as text
+
+     @param {string} parseExt Extension of the parser to use
+     @return {Promise<String>}
+     */
+    toText(parseExt) {
+        const file = this.getFile();
+        const parts = this.getParts();
+        const parser = parseExt ? parsers_1.default.getByExt(parseExt) : file.getParser();
+        if (!parser) {
+            throw error_1.default.FileNotParsableError({
+                filename: file.getPath(),
+            });
+        }
+        return parser.renderSummary({
+            parts: parts.toJS(),
+        });
+    }
+    /**
+     Return all articles as a list
+
+     @return {List<Article>}
+     */
+    getArticlesAsList() {
+        const accu = [];
+        this.getArticle((article) => {
+            accu.push(article);
+        });
+        return immutable_1.default.List(accu);
+    }
+    /**
+     Create a new summary for a list of parts
+
+     @param {Lust|Array} parts
+     @return {Summary}
+     */
+    static createFromParts(file, parts) {
+        parts = parts.map((part, i) => {
+            if (part instanceof summaryPart_1.default) {
+                return part;
+            }
+            return summaryPart_1.default.create(part, i + 1);
+        });
+        return new Summary({
+            file: file,
+            // @ts-expect-error ts-migrate(2350) FIXME: Only a void function can be called with the 'new' ... Remove this comment to see the full error message
+            parts: new immutable_1.default.List(parts),
+        });
+    }
+}
+/**
+ Returns parent level of a level
+
+ @param {string} level
+ @return {string}
+ */
+function getParentLevel(level) {
+    const parts = level.split(".");
+    return parts.slice(0, -1).join(".");
+}
+exports.default = Summary;

package/lib/models/summaryArticle.js

@@ -0,0 +1,169 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const immutable_1 = __importDefault(require("immutable"));
+const location_1 = __importDefault(require("../utils/location"));
+class SummaryArticle extends immutable_1.default.Record({
+    level: String(),
+    title: String(),
+    ref: String(),
+    articles: immutable_1.default.List(),
+}, "SummaryArticle") {
+    getLevel() {
+        return this.get("level");
+    }
+    getTitle() {
+        return this.get("title");
+    }
+    getRef() {
+        return this.get("ref");
+    }
+    getArticles() {
+        return this.get("articles");
+    }
+    /**
+     * Return how deep the article is.
+     * The README has a depth of 1
+     *
+     * @return {number}
+     */
+    getDepth() {
+        return this.getLevel().split(".").length - 1;
+    }
+    /**
+     * Get path (without anchor) to the pointing file.
+     * It also normalizes the file path.
+     *
+     * @return {string}
+     */
+    getPath() {
+        if (this.isExternal()) {
+            return undefined;
+        }
+        const ref = this.getRef();
+        if (!ref) {
+            return undefined;
+        }
+        const parts = ref.split("#");
+        const pathname = parts.length > 1 ? parts.slice(0, -1).join("#") : ref;
+        // Normalize path to remove ('./', '/...', etc)
+        return location_1.default.flatten(pathname);
+    }
+    /**
+     * Return url if article is external
+     *
+     * @return {string}
+     */
+    getUrl() {
+        return this.isExternal() ? this.getRef() : undefined;
+    }
+    /**
+     * Get anchor for this article (or undefined)
+     *
+     * @return {string}
+     */
+    getAnchor() {
+        const ref = this.getRef();
+        const parts = ref.split("#");
+        const anchor = parts.length > 1 ? `#${parts[parts.length - 1]}` : undefined;
+        return anchor;
+    }
+    /**
+     * Create a new level for a new child article
+     *
+     * @return {string}
+     */
+    createChildLevel() {
+        const level = this.getLevel();
+        const subArticles = this.getArticles();
+        const childLevel = `${level}.${subArticles.size + 1}`;
+        return childLevel;
+    }
+    /**
+     * Is article pointing to a page of an absolute url
+     *
+     * @return {boolean}
+     */
+    isPage() {
+        return Boolean(!this.isExternal() && this.getRef());
+    }
+    /**
+     * Check if this article is a file (exatcly)
+     *
+     * @param {File} file
+     * @return {boolean}
+     */
+    isFile(file) {
+        return file.getPath() === this.getPath() && this.getAnchor() === undefined;
+    }
+    /**
+     * Check if this article is the introduction of the book
+     *
+     * @param {Book|Readme} book
+     * @return {boolean}
+     */
+    isReadme(book) {
+        // @ts-expect-error: union
+        const readme = book.getFile ? book : book.getReadme();
+        const file = readme.getFile();
+        return this.isFile(file);
+    }
+    /**
+     * Is article pointing to aan absolute url
+     *
+     * @return {boolean}
+     */
+    isExternal() {
+        return location_1.default.isExternal(this.getRef());
+    }
+    /**
+     * Create a SummaryArticle
+     *
+     * @param {Object} def
+     * @return {SummaryArticle}
+     */
+    static create(def, level) {
+        const articles = (def.articles || []).map((article, i) => {
+            if (article instanceof SummaryArticle) {
+                return article;
+            }
+            return SummaryArticle.create(article, [level, i + 1].join("."));
+        });
+        return new SummaryArticle({
+            level: level,
+            title: def.title,
+            ref: def.ref || def.path || "",
+            articles: immutable_1.default.List(articles),
+        });
+    }
+    /**
+     * Has anchor for this article
+     *
+     * @return {boolean}
+     */
+    hasAnchor() {
+        const ref = this.getRef();
+        return ref.includes("#");
+    }
+    /**
+     * Find an article from a base one
+     *
+     * @param {Article|Part} base
+     * @param {Function(article)} iter
+     * @return {Article}
+     */
+    static findArticle(base, iter) {
+        const articles = base.getArticles();
+        return articles.reduce((result, article) => {
+            if (result)
+                return result;
+            if (iter(article)) {
+                return article;
+            }
+            return SummaryArticle.findArticle(article, iter);
+        }, null);
+    }
+}
+exports.default = SummaryArticle;

package/lib/models/summaryPart.js

@@ -0,0 +1,53 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const immutable_1 = __importDefault(require("immutable"));
+const summaryArticle_1 = __importDefault(require("./summaryArticle"));
+class SummaryPart extends immutable_1.default.Record({
+    level: String(),
+    title: String(),
+    articles: immutable_1.default.List(),
+}) {
+    getLevel() {
+        return this.get("level");
+    }
+    getTitle() {
+        return this.get("title");
+    }
+    getArticles() {
+        return this.get("articles");
+    }
+    /**
+     * Create a new level for a new child article
+     *
+     * @return {string}
+     */
+    createChildLevel() {
+        const level = this.getLevel();
+        const subArticles = this.getArticles();
+        const childLevel = `${level}.${subArticles.size + 1}`;
+        return childLevel;
+    }
+    /**
+     * Create a SummaryPart
+     *
+     * @param {Object} def
+     * @return {SummaryPart}
+     */
+    static create(def, level) {
+        const articles = (def.articles || []).map((article, i) => {
+            if (article instanceof summaryArticle_1.default) {
+                return article;
+            }
+            return summaryArticle_1.default.create(article, [level, i + 1].join("."));
+        });
+        return new SummaryPart({
+            level: String(level),
+            title: def.title,
+            articles: immutable_1.default.List(articles),
+        });
+    }
+}
+exports.default = SummaryPart;

package/lib/models/templateBlock.js

@@ -0,0 +1,230 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const is_1 = __importDefault(require("is"));
+const extend_1 = __importDefault(require("extend"));
+const immutable_1 = __importDefault(require("immutable"));
+const promise_1 = __importDefault(require("../utils/promise"));
+const genKey_1 = __importDefault(require("../utils/genKey"));
+const templateShortcut_1 = __importDefault(require("./templateShortcut"));
+const NODE_ENDARGS = "%%endargs%%";
+class TemplateBlock extends immutable_1.default.Record({
+    // Name of block, also the start tag
+    name: String(),
+    // End tag, default to "end<name>"
+    end: String(),
+    // Function to process the block content
+    process: Function(),
+    // List of String, for inner block tags
+    blocks: immutable_1.default.List(),
+    // List of shortcuts to replace with this block
+    shortcuts: immutable_1.default.Map(),
+}, "TemplateBlock") {
+    getName() {
+        return this.get("name");
+    }
+    getEndTag() {
+        return this.get("end") || `end${this.getName()}`;
+    }
+    getProcess() {
+        return this.get("process");
+    }
+    getBlocks() {
+        return this.get("blocks");
+    }
+    /**
+     * Return shortcuts associated with this block or undefined
+     * @return {TemplateShortcut|undefined}
+     */
+    getShortcuts() {
+        const shortcuts = this.get("shortcuts");
+        if (shortcuts.size === 0) {
+            return undefined;
+        }
+        return templateShortcut_1.default.createForBlock(this, shortcuts);
+    }
+    /**
+     * Return name for the nunjucks extension
+     * @return {string}
+     */
+    getExtensionName() {
+        return `Block${this.getName()}Extension`;
+    }
+    /**
+     * Return a nunjucks extension to represents this block
+     * @return {Nunjucks.Extension}
+     */
+    toNunjucksExt(mainContext, blocksOutput) {
+        blocksOutput = blocksOutput || {};
+        const that = this;
+        const name = this.getName();
+        const endTag = this.getEndTag();
+        const blocks = this.getBlocks().toJS();
+        function Ext() {
+            this.tags = [name];
+            this.parse = function (parser, nodes) {
+                let lastBlockName = null;
+                let lastBlockArgs = null;
+                const allBlocks = blocks.concat([endTag]);
+                // Parse first block
+                const tok = parser.nextToken();
+                lastBlockArgs = parser.parseSignature(null, true);
+                parser.advanceAfterBlockEnd(tok.value);
+                const args = new nodes.NodeList();
+                const bodies = [];
+                const blockNamesNode = new nodes.Array(tok.lineno, tok.colno);
+                const blockArgCounts = new nodes.Array(tok.lineno, tok.colno);
+                // Parse while we found "end<block>"
+                do {
+                    // Read body
+                    const currentBody = parser.parseUntilBlocks.apply(parser, allBlocks);
+                    // Handle body with previous block name and args
+                    blockNamesNode.addChild(new nodes.Literal(args.lineno, args.colno, lastBlockName));
+                    blockArgCounts.addChild(new nodes.Literal(args.lineno, args.colno, lastBlockArgs.children.length));
+                    bodies.push(currentBody);
+                    // Append arguments of this block as arguments of the run function
+                    lastBlockArgs.children.forEach((child) => {
+                        args.addChild(child);
+                    });
+                    // Read new block
+                    lastBlockName = parser.nextToken().value;
+                    // Parse signature and move to the end of the block
+                    if (lastBlockName != endTag) {
+                        lastBlockArgs = parser.parseSignature(null, true);
+                    }
+                    parser.advanceAfterBlockEnd(lastBlockName);
+                } while (lastBlockName != endTag);
+                args.addChild(blockNamesNode);
+                args.addChild(blockArgCounts);
+                args.addChild(new nodes.Literal(args.lineno, args.colno, NODE_ENDARGS));
+                return new nodes.CallExtensionAsync(this, "run", args, bodies);
+            };
+            this.run = function (context) {
+                const fnArgs = Array.prototype.slice.call(arguments, 1);
+                let args;
+                const blocks = [];
+                let bodies = [];
+                // Extract callback
+                const callback = fnArgs.pop();
+                // Detect end of arguments
+                const endArgIndex = fnArgs.indexOf(NODE_ENDARGS);
+                // Extract arguments and bodies
+                args = fnArgs.slice(0, endArgIndex);
+                bodies = fnArgs.slice(endArgIndex + 1);
+                // Extract block counts
+                const blockArgCounts = args.pop();
+                const blockNames = args.pop();
+                // Recreate list of blocks
+                blockNames.forEach((name, i) => {
+                    const countArgs = blockArgCounts[i];
+                    const blockBody = bodies.shift();
+                    const blockArgs = countArgs > 0 ? args.slice(0, countArgs) : [];
+                    args = args.slice(countArgs);
+                    const blockKwargs = extractKwargs(blockArgs);
+                    blocks.push({
+                        name: name,
+                        body: blockBody(),
+                        args: blockArgs,
+                        kwargs: blockKwargs,
+                    });
+                });
+                const mainBlock = blocks.shift();
+                mainBlock.blocks = blocks;
+                promise_1.default()
+                    .then(() => {
+                    const ctx = extend_1.default({
+                        ctx: context,
+                    }, mainContext || {});
+                    return that.applyBlock(mainBlock, ctx);
+                })
+                    .then((result) => {
+                    return that.blockResultToHtml(result, blocksOutput);
+                })
+                    .nodeify(callback);
+            };
+        }
+        // @ts-expect-error: nunjucks.Extension
+        return Ext;
+    }
+    /**
+     * Apply a block to a content
+     * @param {Object} inner
+     * @param {Object} context
+     * @return {Promise<String>|String}
+     */
+    applyBlock(inner, context) {
+        const processFn = this.getProcess();
+        inner = inner || {};
+        inner.args = inner.args || [];
+        inner.kwargs = inner.kwargs || {};
+        inner.blocks = inner.blocks || [];
+        const r = processFn.call(context, inner);
+        if (promise_1.default.isPromiseAlike(r)) {
+            return r.then(this.normalizeBlockResult.bind(this));
+        }
+        else {
+            return this.normalizeBlockResult(r);
+        }
+    }
+    /**
+     * Normalize result from a block process function
+     * @param {Object|String} result
+     * @return {Object}
+     */
+    normalizeBlockResult(result) {
+        if (is_1.default.string(result)) {
+            result = { body: result };
+        }
+        result.name = this.getName();
+        return result;
+    }
+    /**
+     * Convert a block result to HTML
+     * @param {Object} result
+     * @param {Object} blocksOutput: stored post processing blocks in this object
+     * @return {string}
+     */
+    blockResultToHtml(result, blocksOutput) {
+        let indexedKey;
+        const toIndex = !result.parse || result.post !== undefined;
+        if (toIndex) {
+            indexedKey = genKey_1.default();
+            blocksOutput[indexedKey] = result;
+        }
+        // Parsable block, just return it
+        if (result.parse) {
+            return result.body;
+        }
+        // Return it as a position marker
+        return `{{-%${indexedKey}%-}}`;
+    }
+    /**
+     * Create a template block from a function or an object
+     * @param {string} blockName
+     * @param {Object} block
+     * @return {TemplateBlock}
+     */
+    static create(blockName, block) {
+        if (is_1.default.fn(block)) {
+            // @ts-expect-error ts-migrate(2350) FIXME: Only a void function can be called with the 'new' ... Remove this comment to see the full error message
+            block = new immutable_1.default.Map({
+                process: block,
+            });
+        }
+        block = new TemplateBlock(block);
+        block = block.set("name", blockName);
+        return block;
+    }
+}
+/**
+ * Extract kwargs from an arguments array
+ * @param {Array} args
+ * @return {Object}
+ */
+function extractKwargs(args) {
+    const last = args[args.length - 1];
+    return is_1.default.object(last) && last.__keywords ? args.pop() : {};
+}
+exports.default = TemplateBlock;