pict-docuserve 1.3.3 → 1.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pict-docuserve",
-	"version": "1.3.3",
+	"version": "1.3.4",
 	"description": "Pict Documentation Server - A single-page documentation viewer built on Pict",
 	"main": "source/Pict-Application-Docuserve.js",
 	"bin": {
@@ -34,7 +34,7 @@
 		"pict-application": "^1.0.34",
 		"pict-provider": "^1.0.13",
 		"pict-section-code": "^1.0.11",
-		"pict-section-content": "^1.0.3",
+		"pict-section-content": "^1.0.4",
 		"pict-section-histogram": "^1.0.1",
 		"pict-section-modal": "^1.1.1",
 		"pict-section-theme": "^1.0.5",
@@ -42,7 +42,7 @@
 		"pict-view": "^1.0.68"
 	},
 	"devDependencies": {
-		"pict-docuserve": "^1.3.2",
+		"pict-docuserve": "^1.3.3",
 		"quackage": "^1.2.4"
 	},
 	"copyFilesSettings": {

package/source/Pict-Application-Docuserve.js

@@ -583,13 +583,13 @@ class DocuserveApplication extends libPictApplication
 					// Show the README on success, else the original
 					// not-found page (it names the path the user asked for).
 					tmpContentView.displayContent(pReadmeError ? pHTML : pReadmeHTML);
-				});
+				}, '', '', tmpReadmePath);
 				return;
 			}
 			// fetchDocument always provides displayable HTML in pHTML,
 			// even on error, so we can use it directly.
 			tmpContentView.displayContent(pHTML);
-		});
+		}, '', '', tmpPath);
 	}
 
 	/**

package/source/cli/Docuserve-CLI-Program.js

@@ -12,7 +12,8 @@ let _PictCLIProgram = new libCLIProgram(
 		require('./commands/Docuserve-Command-Serve.js'),
 		require('./commands/Docuserve-Command-Inject.js'),
 		require('./commands/Docuserve-Command-PrepareLocal.js'),
-		require('./commands/Docuserve-Command-StageExamples.js')
+		require('./commands/Docuserve-Command-StageExamples.js'),
+		require('./commands/Docuserve-Command-CheckLinks.js')
 	]);
 
 module.exports = _PictCLIProgram;

package/source/cli/commands/Docuserve-Command-CheckLinks.js

@@ -0,0 +1,428 @@
+const libCommandLineCommand = require('pict-service-commandlineutility').ServiceCommandLineCommand;
+
+const libFS = require('fs');
+const libPath = require('path');
+
+/**
+ * Recursively collect every .md file beneath a folder.
+ *
+ * @param {string} pRoot - The folder to walk.
+ * @returns {string[]} Absolute paths of every markdown file found, sorted.
+ */
+function collectMarkdownFiles(pRoot)
+{
+	let tmpResults = [];
+	let tmpStack = [pRoot];
+
+	while (tmpStack.length > 0)
+	{
+		let tmpDir = tmpStack.pop();
+		let tmpEntries;
+		try
+		{
+			tmpEntries = libFS.readdirSync(tmpDir, { withFileTypes: true });
+		}
+		catch (pError)
+		{
+			continue;
+		}
+
+		for (let i = 0; i < tmpEntries.length; i++)
+		{
+			let tmpEntry = tmpEntries[i];
+			let tmpFullPath = libPath.join(tmpDir, tmpEntry.name);
+			if (tmpEntry.isDirectory())
+			{
+				tmpStack.push(tmpFullPath);
+			}
+			else if (tmpEntry.isFile() && /\.md$/i.test(tmpEntry.name))
+			{
+				tmpResults.push(tmpFullPath);
+			}
+		}
+	}
+
+	tmpResults.sort();
+	return tmpResults;
+}
+
+/**
+ * True when a file exists on disk and is a regular file.
+ */
+function fileExists(pPath)
+{
+	try
+	{
+		return libFS.statSync(pPath).isFile();
+	}
+	catch (pError)
+	{
+		return false;
+	}
+}
+
+/**
+ * True when a path exists on disk and is a directory.
+ */
+function directoryExists(pPath)
+{
+	try
+	{
+		return libFS.statSync(pPath).isDirectory();
+	}
+	catch (pError)
+	{
+		return false;
+	}
+}
+
+/**
+ * Resolve a relative href against a base directory, collapsing "." and ".."
+ * segments.  ".." is clamped at the docs root.  Mirrors docuserve module-mode
+ * resolution (Pict-Provider-Docuserve-Documentation._resolveRelativeDocPath)
+ * so the checker resolves .md links exactly the way the viewer routes them.
+ *
+ * @param {string} pBaseDir - The directory the href is relative to (POSIX, docs-root-relative).
+ * @param {string} pHref - The href to resolve.
+ * @returns {string} The resolved docs-root-relative path (no leading slash).
+ */
+function resolveRelativeDocPath(pBaseDir, pHref)
+{
+	let tmpSegments = [];
+	let tmpCombined = (pBaseDir ? pBaseDir + '/' : '') + String(pHref || '');
+	let tmpParts = tmpCombined.split('/');
+	for (let i = 0; i < tmpParts.length; i++)
+	{
+		let tmpPart = tmpParts[i];
+		if ((tmpPart === '') || (tmpPart === '.'))
+		{
+			continue;
+		}
+		if (tmpPart === '..')
+		{
+			if (tmpSegments.length > 0)
+			{
+				tmpSegments.pop();
+			}
+			continue;
+		}
+		tmpSegments.push(tmpPart);
+	}
+	return tmpSegments.join('/');
+}
+
+/**
+ * True when a link target points outside the docs site and must never be
+ * resolved against the filesystem: an absolute or protocol-relative URL, a
+ * scheme such as mailto:/data:/tel:, or a pure #anchor.
+ */
+function isExternalOrAnchor(pTarget)
+{
+	if (!pTarget)
+	{
+		return true;
+	}
+	if (pTarget.charAt(0) === '#')
+	{
+		return true;
+	}
+	if (pTarget.indexOf('//') === 0)
+	{
+		return true;
+	}
+	if (/^[a-z][a-z0-9+.-]*:/i.test(pTarget))
+	{
+		return true;
+	}
+	return false;
+}
+
+/**
+ * Normalize a raw link target extracted from markdown: drop a surrounding
+ * <...>, drop a link title (` "Title"`), drop a #fragment / ?query, and
+ * decode the %5F underscore escape that docuserve's mdSafeUrl introduces.
+ *
+ * @param {string} pRawTarget - The target captured between the link parens.
+ * @returns {string} The cleaned target, ready for filesystem resolution.
+ */
+function cleanTarget(pRawTarget)
+{
+	let tmpTarget = String(pRawTarget || '').trim();
+
+	// Drop an angle-bracket wrapper: [text](<url>) -> url
+	tmpTarget = tmpTarget.replace(/^<+/, '').replace(/>+$/, '');
+
+	// Drop a link title: (url "Title") -> url
+	let tmpSpaceIndex = tmpTarget.search(/\s/);
+	if (tmpSpaceIndex >= 0)
+	{
+		tmpTarget = tmpTarget.substring(0, tmpSpaceIndex);
+	}
+
+	// Drop a #fragment and/or ?query
+	tmpTarget = tmpTarget.split('#')[0].split('?')[0];
+
+	// docuserve's mdSafeUrl percent-encodes underscores; the HTTP layer
+	// decodes them back on fetch, so resolve against the decoded path.
+	tmpTarget = tmpTarget.replace(/%5[fF]/g, '_');
+
+	return tmpTarget.trim();
+}
+
+class DocuserveCommandCheckLinks extends libCommandLineCommand
+{
+	constructor(pFable, pManifest, pServiceHash)
+	{
+		super(pFable, pManifest, pServiceHash);
+
+		this.options.CommandKeyword = 'check-links';
+		this.options.Description = 'Scan a docs folder for unresolvable local links and image/media references.';
+
+		this.options.CommandArguments.push({ Name: '[docs-path]', Description: 'Documentation folder to check (defaults to ./docs/).' });
+
+		this.addCommand();
+	}
+
+	onRun()
+	{
+		let tmpDocsRoot = libPath.resolve(this.ArgumentString || './docs/');
+
+		if (!directoryExists(tmpDocsRoot))
+		{
+			this.log.error(`Docs folder not found at [${tmpDocsRoot}].`);
+			process.exit(1);
+			return;
+		}
+
+		this.log.info(`Checking local links + media references under [${tmpDocsRoot}]...`);
+
+		let tmpFiles = collectMarkdownFiles(tmpDocsRoot);
+		if (tmpFiles.length < 1)
+		{
+			this.log.info(`No markdown files found; nothing to check.`);
+			return;
+		}
+
+		let tmpLinkCount = 0;
+		let tmpImageCount = 0;
+		let tmpBroken = [];
+
+		for (let f = 0; f < tmpFiles.length; f++)
+		{
+			let tmpFilePath = tmpFiles[f];
+			let tmpContent;
+			try
+			{
+				tmpContent = libFS.readFileSync(tmpFilePath, 'utf8');
+			}
+			catch (pError)
+			{
+				this.log.warn(`Could not read [${tmpFilePath}]: ${pError.message}`);
+				continue;
+			}
+
+			let tmpReferences = this._extractReferences(tmpContent);
+			for (let r = 0; r < tmpReferences.length; r++)
+			{
+				let tmpReference = tmpReferences[r];
+
+				if (tmpReference.IsImage)
+				{
+					tmpImageCount++;
+				}
+				else
+				{
+					tmpLinkCount++;
+				}
+
+				let tmpTarget = cleanTarget(tmpReference.Target);
+				if (isExternalOrAnchor(tmpTarget) || (tmpTarget === ''))
+				{
+					continue;
+				}
+
+				let tmpResolution = tmpReference.IsImage
+					? this._resolveImageReference(tmpTarget, tmpFilePath, tmpDocsRoot)
+					: this._resolveDocumentLink(tmpTarget, tmpFilePath, tmpDocsRoot);
+
+				if (!tmpResolution.OK)
+				{
+					tmpBroken.push(
+					{
+						File: libPath.relative(tmpDocsRoot, tmpFilePath),
+						Line: tmpReference.Line,
+						Snippet: tmpReference.Snippet,
+						Reason: tmpResolution.Reason
+					});
+				}
+			}
+		}
+
+		this.log.info(`Checked ${tmpLinkCount} link(s) + ${tmpImageCount} image reference(s) across ${tmpFiles.length} file(s).`);
+
+		if (tmpBroken.length > 0)
+		{
+			this.log.error(`Found ${tmpBroken.length} broken reference(s):`);
+			for (let i = 0; i < tmpBroken.length; i++)
+			{
+				let tmpEntry = tmpBroken[i];
+				this.log.error(`  ${tmpEntry.File}:${tmpEntry.Line}  ${tmpEntry.Snippet}  -> ${tmpEntry.Reason}`);
+			}
+			process.exit(1);
+			return;
+		}
+
+		this.log.info(`All local links + media references resolve.`);
+	}
+
+	/**
+	 * Extract every inline link and image reference from a markdown document.
+	 *
+	 * Fenced code blocks and inline code spans are skipped so that example
+	 * code containing `[text](target)` is never treated as a real link.
+	 *
+	 * @param {string} pContent - The raw markdown text.
+	 * @returns {object[]} { Target, IsImage, Line, Snippet } per reference.
+	 */
+	_extractReferences(pContent)
+	{
+		let tmpReferences = [];
+		let tmpLines = String(pContent).split(/\r?\n/);
+		let tmpInFence = false;
+
+		for (let i = 0; i < tmpLines.length; i++)
+		{
+			let tmpLine = tmpLines[i];
+
+			// Toggle on fenced code block boundaries (backtick fences, to
+			// match the content provider's markdown parser).
+			if (/^\s*`{3,}/.test(tmpLine))
+			{
+				tmpInFence = !tmpInFence;
+				continue;
+			}
+			if (tmpInFence)
+			{
+				continue;
+			}
+
+			// Drop inline code spans so `[x](y)` in backticks is not a link.
+			let tmpScrubbed = tmpLine.replace(/`[^`]*`/g, ' ');
+
+			// Images: ![alt](target)
+			let tmpImageRegEx = /!\[[^\]]*\]\(([^)]+)\)/g;
+			let tmpImageMatch;
+			while ((tmpImageMatch = tmpImageRegEx.exec(tmpScrubbed)) !== null)
+			{
+				tmpReferences.push(
+				{
+					Target: tmpImageMatch[1],
+					IsImage: true,
+					Line: i + 1,
+					Snippet: tmpImageMatch[0]
+				});
+			}
+
+			// Links: [text](target) — the [^!] guard excludes image links.
+			let tmpLinkRegEx = /(^|[^!])(\[[^\]]*\]\(([^)]+)\))/g;
+			let tmpLinkMatch;
+			while ((tmpLinkMatch = tmpLinkRegEx.exec(tmpScrubbed)) !== null)
+			{
+				tmpReferences.push(
+				{
+					Target: tmpLinkMatch[3],
+					IsImage: false,
+					Line: i + 1,
+					Snippet: tmpLinkMatch[2]
+				});
+			}
+		}
+
+		return tmpReferences;
+	}
+
+	/**
+	 * Resolve a documentation link the way docuserve module-mode renders it,
+	 * and report whether the target exists on disk.
+	 *
+	 * Every relative link — a .md page, a .html app, a directory, a media
+	 * file — is resolved against the directory of the document that contains
+	 * it, with ../ clamped at the docs root.  A /-rooted link is resolved
+	 * against the docs root.
+	 *
+	 * @param {string} pTarget - The cleaned link target.
+	 * @param {string} pCurrentFile - Absolute path of the file the link is in.
+	 * @param {string} pDocsRoot - The absolute docs root folder.
+	 * @returns {object} { OK, Reason }
+	 */
+	_resolveDocumentLink(pTarget, pCurrentFile, pDocsRoot)
+	{
+		let tmpBaseDir = '';
+		let tmpHref = pTarget;
+		if (pTarget.charAt(0) === '/')
+		{
+			tmpHref = pTarget.replace(/^\/+/, '');
+		}
+		else
+		{
+			tmpBaseDir = libPath.relative(pDocsRoot, libPath.dirname(pCurrentFile)).split(libPath.sep).join('/');
+		}
+		let tmpResolved = libPath.join(pDocsRoot, resolveRelativeDocPath(tmpBaseDir, tmpHref));
+
+		if (fileExists(tmpResolved) || directoryExists(tmpResolved))
+		{
+			return { OK: true };
+		}
+
+		// An extensionless target may be a directory or an extensionless page
+		// route — docuserve's page route also tries <target>.md and
+		// <target>/README.md, so accept those too.
+		let tmpBareTarget = pTarget.replace(/[#?].*$/, '').replace(/\/+$/, '');
+		if (/\.md$/i.test(pTarget) || !/\.[a-z0-9]+$/i.test(tmpBareTarget))
+		{
+			if (fileExists(tmpResolved + '.md') || fileExists(libPath.join(tmpResolved, 'README.md')))
+			{
+				return { OK: true };
+			}
+		}
+
+		return { OK: false, Reason: `no file at ${libPath.relative(pDocsRoot, tmpResolved) || '.'}` };
+	}
+
+	/**
+	 * Resolve an image/media reference the way docuserve's image resolver does
+	 * — relative to the containing document's directory, or docs-root-relative
+	 * when the target is /-rooted — and report whether it exists on disk.
+	 *
+	 * @param {string} pTarget - The cleaned image target.
+	 * @param {string} pCurrentFile - Absolute path of the file the ref is in.
+	 * @param {string} pDocsRoot - The absolute docs root folder.
+	 * @returns {object} { OK, Reason }
+	 */
+	_resolveImageReference(pTarget, pCurrentFile, pDocsRoot)
+	{
+		let tmpResolved;
+		if (pTarget.charAt(0) === '/')
+		{
+			tmpResolved = libPath.normalize(libPath.join(pDocsRoot, pTarget.replace(/^\/+/, '')));
+		}
+		else
+		{
+			tmpResolved = libPath.normalize(libPath.join(libPath.dirname(pCurrentFile), pTarget));
+		}
+
+		if ((tmpResolved !== pDocsRoot) && (tmpResolved.indexOf(pDocsRoot + libPath.sep) !== 0))
+		{
+			return { OK: false, Reason: 'resolves outside the docs root' };
+		}
+
+		if (fileExists(tmpResolved))
+		{
+			return { OK: true };
+		}
+
+		return { OK: false, Reason: `no file at ${libPath.relative(pDocsRoot, tmpResolved) || '.'}` };
+	}
+}
+
+module.exports = DocuserveCommandCheckLinks;

package/source/cli/commands/Docuserve-Command-StageExamples.js

@@ -275,7 +275,7 @@ class DocuserveCommandStageExamples extends libCommandLineCommand
 			return;
 		}
 
-		// Regenerate the marker-delimited index + intro quick-links.
+		// Regenerate the marker-delimited examples index + the splash region.
 		try
 		{
 			this._writeExamplesIndex(tmpStaged, tmpDocsFolder);
@@ -287,11 +287,11 @@ class DocuserveCommandStageExamples extends libCommandLineCommand
 
 		try
 		{
-			this._writeIntroQuickLinks(tmpStaged, tmpDocsFolder);
+			this._writeCoverExamples(tmpStaged, tmpDocsFolder);
 		}
 		catch (pError)
 		{
-			this.log.warn(`Could not update intro quick-links: ${pError.message}`);
+			this.log.warn(`Could not update splash examples region: ${pError.message}`);
 		}
 
 		this.log.info(`Staged ${tmpStaged.length} example application(s): ${tmpStaged.map((pEx) => pEx.Name).join(', ')}`);
@@ -492,7 +492,10 @@ class DocuserveCommandStageExamples extends libCommandLineCommand
 		let tmpTitle = pExample.Flag.Title || tmpName;
 		let tmpSummary = pExample.Flag.Summary || pExample.Package.description || '';
 
-		let tmpInner = `> **[▶ Launch the live app](${mdSafeUrl('examples/' + tmpName + '/index.html')})** — runs in your browser, opens in a new tab.`;
+		// The writeup lives at docs/examples/<name>/README.md, so index.html
+		// is its sibling — a document-relative href docuserve resolves the
+		// same way it resolves the writeup's other links.
+		let tmpInner = `> **[&#9654; Launch the live app](index.html)** — runs in your browser, opens in a new tab.`;
 
 		let tmpText;
 		if (libFS.existsSync(tmpReadmePath))
@@ -536,7 +539,9 @@ class DocuserveCommandStageExamples extends libCommandLineCommand
 		let tmpRows = pStaged.map((pEx) =>
 		{
 			let tmpComplexity = escapeTableCell(pEx.Complexity) || '—';
-			return `| [${escapeTableCell(pEx.Title)}](${mdSafeUrl('examples/' + pEx.Name + '/README.md')}) | ${tmpComplexity} | ${escapeTableCell(pEx.Summary)} | [&#9654; Launch](${mdSafeUrl('examples/' + pEx.Name + '/index.html')}) |`;
+			// Both links are relative to this index (docs/examples/README.md),
+			// so they omit the examples/ segment.
+			return `| [${escapeTableCell(pEx.Title)}](${mdSafeUrl(pEx.Name + '/README.md')}) | ${tmpComplexity} | ${escapeTableCell(pEx.Summary)} | [&#9654; Launch](${mdSafeUrl(pEx.Name + '/index.html')}) |`;
 		});
 		let tmpInner = [
 			'| Example | Complexity | Summary | Live |',
@@ -558,43 +563,43 @@ class DocuserveCommandStageExamples extends libCommandLineCommand
 	}
 
 	/**
-	 * Maintain the generated "Example Applications" quick-links block on the
-	 * documentation intro page at docs/README.md.
+	 * Maintain the generated examples region in docs/_cover.md.  docuserve's
+	 * Splash view renders this region as the "Interactive Examples" section of
+	 * the landing page.  When _cover.md is absent the region is not created —
+	 * the splash simply shows no examples section.
 	 *
 	 * @param {object[]} pStaged - Staged example metadata.
 	 * @param {string} pDocsFolder - The target documentation folder.
 	 */
-	_writeIntroQuickLinks(pStaged, pDocsFolder)
+	_writeCoverExamples(pStaged, pDocsFolder)
 	{
-		let tmpReadmePath = libPath.join(pDocsFolder, 'README.md');
+		let tmpCoverPath = libPath.join(pDocsFolder, '_cover.md');
+		if (!libFS.existsSync(tmpCoverPath))
+		{
+			this.log.info(`No _cover.md at [${tmpCoverPath}]; skipping splash examples region.`);
+			return;
+		}
 
-		let tmpBullets = pStaged.map((pEx) =>
+		let tmpRows = pStaged.map((pEx) =>
 		{
-			let tmpSummary = String(pEx.Summary || '').replace(/\r?\n/g, ' ').trim();
-			return `- **[${pEx.Title}](${mdSafeUrl('examples/' + pEx.Name + '/README.md')})** — ${tmpSummary} · [&#9654; Launch live app](${mdSafeUrl('examples/' + pEx.Name + '/index.html')})`;
+			let tmpComplexity = escapeTableCell(pEx.Complexity) || '—';
+			return `| [${escapeTableCell(pEx.Title)}](${mdSafeUrl('examples/' + pEx.Name + '/README.md')}) | ${tmpComplexity} | [&#9654; Launch](${mdSafeUrl('examples/' + pEx.Name + '/index.html')}) |`;
 		});
-		let tmpInner = '*Live, runnable example applications — each opens in a new browser tab:*\n\n' + tmpBullets.join('\n');
+		let tmpInner = [
+			'| Example | Complexity | Launch |',
+			'|---------|------------|--------|'
+		].concat(tmpRows).join('\n');
 
-		let tmpText = libFS.existsSync(tmpReadmePath)
-			? libFS.readFileSync(tmpReadmePath, 'utf8')
-			: '# Documentation\n';
+		let tmpText = libFS.readFileSync(tmpCoverPath, 'utf8');
 
 		tmpText = replaceRegion(tmpText, _Marker.QuickLinksStart, _Marker.QuickLinksEnd, tmpInner,
 			(pBody, pRegion) =>
 			{
-				// Prefer to place the block directly under an existing
-				// "Example Applications" heading.
-				let tmpHeading = pBody.match(/^#{2,}\s+Example Applications\s*$/m);
-				if (tmpHeading)
-				{
-					let tmpIndex = pBody.indexOf(tmpHeading[0]) + tmpHeading[0].length;
-					return pBody.substring(0, tmpIndex) + '\n\n' + pRegion + '\n' + pBody.substring(tmpIndex);
-				}
-				// Otherwise append a new section at the end of the page.
-				return pBody.replace(/\s*$/, '') + '\n\n## Example Applications\n\n' + pRegion + '\n';
+				// No markers yet — append the region at the end of the cover.
+				return pBody.replace(/\s*$/, '') + '\n\n' + pRegion + '\n';
 			});
 
-		libFS.writeFileSync(tmpReadmePath, tmpText);
+		libFS.writeFileSync(tmpCoverPath, tmpText);
 	}
 }