@rohal12/twee-ts 1.16.1 → 1.17.0

package/dist/index.js

@@ -4696,14 +4696,16 @@ function parseDocument(data, options) {
 */
 /**
 * Parse a Twine 2 or Twine 1 compiled HTML file back into a Story model.
+* Tweego always trims passage text; here `trim: false` keeps it exactly, as for Twee sources.
 */
-function decompileHTML(html) {
+function decompileHTML(html, options = {}) {
 	const diagnostics = [];
 	const story = createStory();
+	const passageText = options.trim === false ? (text) => text : (text) => text.trim();
 	const doc = parseDocument(html);
 	const twine2Data = findElement(doc, "tw-storydata");
 	if (twine2Data) {
-		decompileTwine2(twine2Data, story, diagnostics);
+		decompileTwine2(twine2Data, story, passageText, diagnostics);
 		return {
 			story,
 			diagnostics
@@ -4711,7 +4713,7 @@ function decompileHTML(html) {
 	}
 	const twine1Data = findElementByIdPattern(doc, /^store(?:-a|A)rea$/);
 	if (twine1Data) {
-		decompileTwine1(twine1Data, story, diagnostics);
+		decompileTwine1(twine1Data, story, passageText, diagnostics);
 		return {
 			story,
 			diagnostics
@@ -4726,7 +4728,7 @@ function decompileHTML(html) {
 		diagnostics
 	};
 }
-function decompileTwine2(storyData, story, diagnostics) {
+function decompileTwine2(storyData, story, passageText, diagnostics) {
 	let startnode = 0;
 	const attrs = storyData.attribs ?? {};
 	if (attrs["name"]) story.name = attrs["name"];
@@ -4756,8 +4758,9 @@ function decompileTwine2(storyData, story, diagnostics) {
 		switch (node.name) {
 			case "style":
 			case "script": {
-				const text = getTextContent(node).trim();
-				if (text.length === 0) continue;
+				const content = getTextContent(node);
+				if (content.trim().length === 0) continue;
+				const text = passageText(content);
 				storyAdd(story, {
 					name: node.name === "style" ? "Story Stylesheet" : "Story JavaScript",
 					tags: node.name === "style" ? ["stylesheet"] : ["script"],
@@ -4792,7 +4795,7 @@ function decompileTwine2(storyData, story, diagnostics) {
 				const passage = {
 					name,
 					tags,
-					text: getTextContent(node).trim()
+					text: passageText(getTextContent(node))
 				};
 				if (metadata.position || metadata.size) passage.metadata = metadata;
 				storyAdd(story, passage, diagnostics);
@@ -4806,8 +4809,8 @@ function decompileTwine2(storyData, story, diagnostics) {
 		text: marshalStoryData(story)
 	}, diagnostics);
 }
-function decompileTwine1(storeArea, story, diagnostics) {
-	const passages = (storeArea.children ?? []).filter(isTiddler).map(tiddlerToPassage);
+function decompileTwine1(storeArea, story, passageText, diagnostics) {
+	const passages = (storeArea.children ?? []).filter(isTiddler).map((node) => tiddlerToPassage(node, passageText));
 	const obfuscated = isRot13Obfuscated(passages);
 	for (const p of passages) storyAdd(story, obfuscated && p.name !== "StorySettings" ? {
 		...p,
@@ -4817,12 +4820,12 @@ function decompileTwine1(storeArea, story, diagnostics) {
 function isTiddler(node) {
 	return node.type === "tag" && node.name === "div" && node.attribs !== void 0 && "tiddler" in node.attribs;
 }
-function tiddlerToPassage(node) {
+function tiddlerToPassage(node, passageText) {
 	const nodeAttrs = node.attribs ?? {};
 	const passage = {
 		name: nodeAttrs["tiddler"] ?? "",
 		tags: nodeAttrs["tags"] ? nodeAttrs["tags"].split(/\s+/).filter((s) => s.length > 0) : [],
-		text: tiddlerUnescape(getTextContent(node)).trim()
+		text: passageText(tiddlerUnescape(getTextContent(node)))
 	};
 	const position = nodeAttrs["twine-position"];
 	if (position) passage.metadata = { position };
@@ -4887,7 +4890,7 @@ function loadSources(story, filenames, opts, diagnostics, processedFiles) {
 					break;
 				case "htm":
 				case "html":
-					loadHTML(story, filename, diagnostics);
+					loadHTML(story, filename, opts, diagnostics);
 					break;
 				case "css":
 					loadTagged(story, "stylesheet", filename, diagnostics);
@@ -5041,8 +5044,8 @@ function parseFontFile(filename) {
 		diagnostics: []
 	};
 }
-function parseHTMLFile(filename) {
-	const { story, diagnostics } = decompileHTML(readUTF8(filename));
+function parseHTMLFile(filename, opts) {
+	const { story, diagnostics } = decompileHTML(readUTF8(filename), { trim: opts.trim ?? true });
 	return {
 		passages: story.name !== "" && !storyHas(story, "StoryTitle") ? [{
 			name: "StoryTitle",
@@ -5054,14 +5057,17 @@ function parseHTMLFile(filename) {
 }
 /**
 * Identity of the options that affect how a file parses, stored on its cache entry.
-* Only Twee files depend on them; every other file type yields the same key for all options.
+* Twee files depend on `trim` and `twee2Compat`, HTML files on `trim`; every other file type
+* yields the same key for all options.
 */
 function parseOptionsKey(filename, opts) {
 	const ext = normalizedFileExt(filename);
+	const trim = opts.trim ?? true;
+	if (ext === "htm" || ext === "html") return JSON.stringify({ trim });
 	const twee2File = ext === "tw2" || ext === "twee2";
 	if (!twee2File && ext !== "tw" && ext !== "twee") return "";
 	return JSON.stringify({
-		trim: opts.trim ?? true,
+		trim,
 		twee2Compat: twee2File || (opts.twee2Compat ?? false)
 	});
 }
@@ -5075,7 +5081,7 @@ function parseFile(filename, opts) {
 			twee2Compat: true
 		});
 		case "htm":
-		case "html": return parseHTMLFile(filename);
+		case "html": return parseHTMLFile(filename, opts);
 		case "css": return parseTaggedFile("stylesheet", filename);
 		case "js": return parseTaggedFile("script", filename);
 		case "otf":
@@ -5107,8 +5113,8 @@ function parseFile(filename, opts) {
 		default: return;
 	}
 }
-function loadHTML(story, filename, diagnostics) {
-	const result = parseHTMLFile(filename);
+function loadHTML(story, filename, opts, diagnostics) {
+	const result = parseHTMLFile(filename, opts);
 	diagnostics.push(...result.diagnostics);
 	for (const p of result.passages) storyAdd(story, p, diagnostics);
 }
@@ -5147,7 +5153,8 @@ function loadSourcesCached(story, filenames, opts, diagnostics, processedFiles,
 		const optionsKey = parseOptionsKey(filename, opts);
 		const entry = cache.get(filename);
 		const cached = entry?.parseOptionsKey === optionsKey ? entry : void 0;
-		if (changedFiles && cached && !changedFiles.has(filename)) {
+		const changed = changedFiles?.has(filename) ?? false;
+		if (changedFiles && cached && !changed) {
 			diagnostics.push(...cached.diagnostics);
 			for (const p of cached.passages) storyAdd(story, p, diagnostics);
 			processedFiles.add(filename);
@@ -5159,7 +5166,7 @@ function loadSourcesCached(story, filenames, opts, diagnostics, processedFiles,
 		} catch {
 			continue;
 		}
-		if (cached && cached.mtimeMs === mtimeMs) {
+		if (cached && !changed && cached.mtimeMs === mtimeMs) {
 			diagnostics.push(...cached.diagnostics);
 			for (const p of cached.passages) storyAdd(story, p, diagnostics);
 			processedFiles.add(filename);
@@ -5407,10 +5414,39 @@ function tryReplaceComponent(template, placeholder, componentPath, required) {
 }
 //#endregion
 //#region src/output-twee.ts
-function toTwee(story, outMode) {
-	let data = "";
-	for (const p of story.passages) data += passageToTwee(p, outMode);
-	return data;
+/**
+* Serialize the story as Twee. The StoryData passage is written from the story model rather than
+* from its loaded text, so changes made after loading (a start passage override, test mode) are kept.
+* Tweego writes the loaded text; its own normalization makes the two the same for an unchanged story.
+*
+* `addStoryData`: add a StoryData passage when the story has none, so that StoryData fields the
+* compile options set are recorded. Default: false.
+*/
+function toTwee(story, outMode, options = {}) {
+	return withEffectiveStoryData(story, options.addStoryData ?? false).map((p) => passageToTwee(p, outMode)).join("");
+}
+function withEffectiveStoryData(story, addStoryData) {
+	const storyData = {
+		name: "StoryData",
+		tags: [],
+		text: marshalStoryData(story)
+	};
+	const index = story.passages.findIndex((p) => p.name === "StoryData");
+	if (index !== -1) return story.passages.map((p, i) => i === index && isStoryDataJSON(p.text) ? {
+		...p,
+		text: storyData.text
+	} : p);
+	if (!addStoryData) return story.passages;
+	const at = story.passages[0]?.name === "StoryTitle" ? 1 : 0;
+	return [
+		...story.passages.slice(0, at),
+		storyData,
+		...story.passages.slice(at)
+	];
+}
+/** Whether the text loaded as StoryData. Text that did not is kept as written, for the author to fix. */
+function isStoryDataJSON(text) {
+	return unmarshalStoryData(createStory(), text) === null;
 }
 //#endregion
 //#region src/modules.ts
@@ -5482,7 +5518,19 @@ function modifyHead(html, modulePaths, headFile, diagnostics) {
 	return html;
 }
 //#endregion
-//#region src/start-passage.ts
+//#region src/passage-omission.ts
+/**
+* Why the `target` output leaves `passage` out of its passage elements, or `undefined` when it
+* emits the passage (and so a link or the start can name it).
+*/
+function passageOmission(story, passage, target) {
+	switch (target) {
+		case "twine2": return twine2PassageOmission(story, passage);
+		case "twine1": return twine1PassageOmission(passage);
+		default: throw new Error(`unhandled passage output target: ${String(target)}`);
+	}
+}
+/** Why a passage is left out, as a predicate: `Passage "X" ${describeOmission(o)}`. */
 function describeOmission(omission) {
 	switch (omission.kind) {
 		case "special-name": return `is the special "${omission.name}" passage`;
@@ -5491,13 +5539,8 @@ function describeOmission(omission) {
 		default: throw new Error(`unhandled passage omission: ${JSON.stringify(omission)}`);
 	}
 }
-function omissionFor(story, passage, target) {
-	switch (target) {
-		case "twine2": return twine2PassageOmission(story, passage);
-		case "twine1": return twine1PassageOmission(passage);
-		default: throw new Error(`unhandled start passage target: ${String(target)}`);
-	}
-}
+//#endregion
+//#region src/start-passage.ts
 /**
 * Check that `startName` names a passage the `target` output emits.
 * Returns the error diagnostics to report (empty when the start is usable).
@@ -5508,7 +5551,7 @@ function startPassageDiagnostics(story, startName, target) {
 		level: "error",
 		message: `Starting passage "${startName}" not found.`
 	}];
-	const omission = omissionFor(story, passage, target);
+	const omission = passageOmission(story, passage, target);
 	if (omission === void 0) return [];
 	return [{
 		level: "error",
@@ -5543,21 +5586,48 @@ async function compile(options) {
 * Compile and write to a file.
 */
 async function compileToFile(options) {
-	const result = await buildOutput(options, void 0, void 0, options.outFile);
+	const result = await compileForOutputFile(options, options.outFile);
 	writeFileSync(options.outFile, result.output, "utf-8");
 	return result;
 }
 /**
+* Builds as compileToFile() does for `outFile`, without writing it: the output may sit
+* inside a source folder, so its last build is left out of the sources and modules and
+* never read back. The caller decides whether the result is written. With no `outFile`
+* (output to stdout, or none), this is compile().
+*
+* Internal, for the CLI; not part of the public API.
+*/
+async function compileForOutputFile(options, outFile) {
+	return buildOutput(options, void 0, void 0, outFile);
+}
+/**
 * Compile with incremental caching support.
 * Plugins and advanced users can manage their own cache and changed-file tracking.
+*
+* Without `changedFiles`, a cached file is reused while its modification time is unchanged.
+* With it, a file it names (by the path source discovery gives it, relative to the working
+* directory) is always reparsed, whatever its modification time, and every other cached
+* file is reused as it is.
 */
 async function compileIncremental(options, cache, changedFiles) {
 	return buildOutput(options, cache, changedFiles);
 }
 /**
-* Watch for file changes and recompile.
+* Watch for file changes and recompile. Every build is written to `outFile`, including
+* one whose diagnostics report errors.
 */
 async function watch(options) {
+	return watchWithWriteFilter(options, () => true);
+}
+/**
+* watch(), writing to `outFile` only the builds `shouldWrite` accepts. A rejected build
+* leaves the output file as it was; `onBuild` receives every build either way.
+*
+* Internal, for the CLI, which keeps the last good output when a rebuild reports errors;
+* not part of the public API.
+*/
+async function watchWithWriteFilter(options, shouldWrite) {
 	const controller = new AbortController();
 	const cache = /* @__PURE__ */ new Map();
 	const filePaths = options.sources.filter((s) => typeof s === "string");
@@ -5577,7 +5647,7 @@ async function watch(options) {
 	};
 	const handle = watchFilesystem(allPaths, options.outFile, (changedFiles) => {
 		buildOutput(options, cache, changedFiles, options.outFile).then((result) => {
-			writeFileSync(options.outFile, result.output, "utf-8");
+			if (shouldWrite(result)) writeFileSync(options.outFile, result.output, "utf-8");
 			options.onBuild?.(result);
 		}).catch((e) => {
 			options.onError?.(e instanceof Error ? e : new Error(String(e)));
@@ -5633,7 +5703,7 @@ async function buildOutput(options, cache, changedFiles, outFile) {
 	switch (outputMode) {
 		case "twee3":
 		case "twee1":
-			output = toTwee(story, outputMode);
+			output = toTwee(story, outputMode, { addStoryData: Boolean(options.startPassage) || testMode });
 			break;
 		case "twine2-archive":
 			output = toTwine2Archive(story, startName, { sourceInfo });
@@ -6076,6 +6146,11 @@ function endOfRegularExpression(source, pos) {
 }
 //#endregion
 //#region src/link-markup.ts
+/** Records that the reading has looked at the characters before `pos`, and returns `result`. */
+function readTo(reader, pos, result) {
+	reader.scanned = Math.max(reader.scanned, pos);
+	return result;
+}
 /**
 * Reads link or image markup that starts at `start` in `text`, or returns `undefined` where
 * SugarCube rejects it (and so prints the text instead).
@@ -6083,15 +6158,17 @@ function endOfRegularExpression(source, pos) {
 * `budget.left`, if given, is how many characters the reading may look at; it is reduced by as
 * many as were read, and once it runs out, every reading fails. Unclosed markup is read to the end
 * of its line, so reading every `[[` of a long line that never closes one would otherwise take
-* quadratic time.
+* quadratic time. A reading is charged for the characters it looked at, up to where it ended or
+* failed (a line feed, say), and no more, so markup left unclosed on short lines costs little.
 */
 function readSquareBracketedMarkup(text, start, budget = { left: Infinity }) {
 	const reader = {
 		text,
-		limit: Math.min(text.length, start + Math.max(budget.left, 0))
+		limit: Math.min(text.length, start + Math.max(budget.left, 0)),
+		scanned: start
 	};
 	const markup = readMarkup(reader, start);
-	budget.left -= (markup?.end ?? reader.limit) - start;
+	budget.left -= Math.max(reader.scanned, markup?.end ?? start) - start;
 	return markup;
 }
 function readMarkup(reader, start) {
@@ -6167,7 +6244,7 @@ function readCoreComponents(reader, from) {
 		const ch = text[pos];
 		pos += 1;
 		switch (ch) {
-			case "\n": return;
+			case "\n": return readTo(reader, pos, void 0);
 			case "\"": {
 				const end = readQuoted(reader, pos, "\"");
 				if (end === void 0) return;
@@ -6201,7 +6278,7 @@ function readCoreComponents(reader, from) {
 			case "]":
 				depth -= 1;
 				if (depth === 1) {
-					const end = componentEnd(text, pos);
+					const end = componentEnd(reader, pos);
 					if (end === void 0) return;
 					return {
 						link: link ?? text.slice(componentStart, end.textEnd),
@@ -6210,6 +6287,7 @@ function readCoreComponents(reader, from) {
 				}
 		}
 	}
+	return readTo(reader, pos, void 0);
 }
 /**
 * Reads a component after `][` that holds no delimiter: an image's link (`setter` false) or a
@@ -6223,7 +6301,7 @@ function readComponent(reader, from, setter) {
 		const ch = text[pos];
 		pos += 1;
 		switch (ch) {
-			case "\n": return;
+			case "\n": return readTo(reader, pos, void 0);
 			case "\"":
 			case "'": {
 				if (ch === "'" && !setter) break;
@@ -6237,9 +6315,10 @@ function readComponent(reader, from, setter) {
 				break;
 			case "]":
 				depth -= 1;
-				if (depth === 1) return componentEnd(text, pos);
+				if (depth === 1) return componentEnd(reader, pos);
 		}
 	}
+	return readTo(reader, pos, void 0);
 }
 /** Reads a setter, the last component; returns the index after its closing `]]`. */
 function readSetter(reader, from) {
@@ -6247,19 +6326,19 @@ function readSetter(reader, from) {
 	return end?.last === true ? end.next : void 0;
 }
 /** What the `]` just before `pos`, which brings the depth back to one, ends; `undefined` if malformed. */
-function componentEnd(text, pos) {
-	switch (text[pos]) {
-		case "[": return {
+function componentEnd(reader, pos) {
+	switch (reader.text[pos]) {
+		case "[": return readTo(reader, pos + 1, {
 			textEnd: pos - 1,
 			next: pos + 1,
 			last: false
-		};
-		case "]": return {
+		});
+		case "]": return readTo(reader, pos + 1, {
 			textEnd: pos - 1,
 			next: pos + 1,
 			last: true
-		};
-		default: return;
+		});
+		default: return readTo(reader, pos + 1, void 0);
 	}
 }
 /**
@@ -6274,12 +6353,13 @@ function readQuoted(reader, from, quote) {
 		const ch = text[pos];
 		pos += 1;
 		if (ch === quote) return pos;
-		if (ch === "\n") return;
+		if (ch === "\n") return readTo(reader, pos, void 0);
 		if (ch === "\\") {
-			if (pos >= reader.limit || text[pos] === "\n") return;
+			if (pos >= reader.limit || text[pos] === "\n") return readTo(reader, Math.min(pos + 1, reader.limit), void 0);
 			pos += 1;
 		}
 	}
+	return readTo(reader, pos, void 0);
 }
 //#endregion
 //#region src/sugarcube-macros.ts
@@ -7137,6 +7217,29 @@ function extractLinksFromText(text, isScript) {
 	].flatMap((via) => found.filter((link) => link.via === via).map((link) => link.passage));
 	return [...new Set(ordered)];
 }
+/**
+* The passages that `p` links to. A script passage is JavaScript, read for links only in its
+* strings. A stylesheet is CSS, which the story puts in a style element and never wikifies, so it
+* links nowhere; a passage tagged both is a script, as Twine 2 output takes it.
+*/
+function passageLinks(p) {
+	if (hasTag(p, "script")) return extractLinksFromText(textAsRead(p), true);
+	if (hasTag(p, "stylesheet")) return [];
+	return extractLinksFromText(textAsRead(p), false);
+}
+/**
+* Each passage name, mapped to why the `target` output leaves that passage out, or to `undefined`
+* when a link can reach it: always without a target, and otherwise when the output emits a
+* passage of that name.
+*/
+function destinationOmissions(story, { target }) {
+	const omissions = /* @__PURE__ */ new Map();
+	for (const p of story.passages) {
+		const omission = target === void 0 ? void 0 : passageOmission(story, p, target);
+		if (!omissions.has(p.name) || omission === void 0) omissions.set(p.name, omission);
+	}
+	return omissions;
+}
 /** Passages SugarCube runs from their raw text, never joining their lines. */
 const RAW_TEXT_PASSAGES = /* @__PURE__ */ new Set([
 	"StoryInit",
@@ -7178,9 +7281,14 @@ function joinLines(text) {
 * expect(map.brokenLinks).toEqual([]);
 * expect(map.deadEnds).not.toContain('Start');
 * ```
+*
+* By default, a link is broken only when no passage has its name. Pass a `target` to check links
+* against what that output emits: `storyInspect(result.story, { target: 'twine2' })` also reports
+* links to passages Twine 2 output leaves out, such as script, stylesheet and `Twine.private`
+* passages.
 */
-function storyInspect(story) {
-	const allNames = new Set(story.passages.map((p) => p.name));
+function storyInspect(story, options = {}) {
+	const destinations = destinationOmissions(story, options);
 	const passages = [];
 	const storyPassages = [];
 	const infoPassages = [];
@@ -7202,14 +7310,24 @@ function storyInspect(story) {
 			}
 			list.push(p.name);
 		}
-		const targets = extractLinksFromText(textAsRead(p), hasTag(p, "script"));
-		links.set(p.name, targets);
+		links.set(p.name, passageLinks(p));
 	}
 	const brokenLinks = [];
-	for (const [from, targets] of links) for (const to of targets) if (!allNames.has(to)) brokenLinks.push({
-		from,
-		to
-	});
+	for (const [from, targets] of links) for (const to of targets) {
+		if (!destinations.has(to)) {
+			brokenLinks.push({
+				from,
+				to
+			});
+			continue;
+		}
+		const omission = destinations.get(to);
+		if (omission !== void 0) brokenLinks.push({
+			from,
+			to,
+			omission
+		});
+	}
 	const deadEnds = [];
 	for (const name of storyPassages) {
 		const targets = links.get(name);
@@ -7239,14 +7357,26 @@ function storyInspect(story) {
 /**
 * Lint a story: compile without output rendering, then inspect structure.
 * Uses JSON output mode internally to avoid format resolution, so it checks
-* the starting passage itself, against the Twine 2 passage rules.
+* the starting passage itself, against the Twine 2 passage rules. Link
+* destinations are checked against the same rules: a link to a passage that
+* Twine 2 output leaves out is broken.
 */
 async function lint(options) {
-	const result = await compile({
+	return lintForOutputFile(options, void 0);
+}
+/**
+* lint() for a project whose builds are written to `outFile`: like a build for that file,
+* it leaves `outFile` out of the sources and modules, so an earlier build inside a source
+* folder is not linted as a source.
+*
+* Internal, for the CLI; not part of the public API.
+*/
+async function lintForOutputFile(options, outFile) {
+	const result = await compileForOutputFile({
 		...options,
 		outputMode: "json"
-	});
-	const map = storyInspect(result.story);
+	}, outFile);
+	const map = storyInspect(result.story, { target: "twine2" });
 	return {
 		diagnostics: [...result.diagnostics, ...startPassageDiagnostics(result.story, map.start, "twine2")],
 		stats: result.stats,
@@ -7273,7 +7403,10 @@ function formatLintReport(result) {
 	if (result.brokenLinks.length > 0) {
 		lines.push("");
 		lines.push(`Broken links (${result.brokenLinks.length}):`);
-		for (const link of result.brokenLinks) lines.push(`  ${link.from} -> ${link.to} (passage "${link.to}" does not exist)`);
+		for (const link of result.brokenLinks) {
+			const why = link.omission === void 0 ? "does not exist" : `${describeOmission(link.omission)}, so it is left out of the story data`;
+			lines.push(`  ${link.from} -> ${link.to} (passage "${link.to}" ${why})`);
+		}
 	}
 	if (result.deadEnds.length > 0) {
 		lines.push("");