@rohal12/twee-ts 1.5.0 → 1.7.0

package/dist/index.d.cts

@@ -261,6 +261,45 @@ interface BrokenLink {
  */
 declare function storyInspect(story: Story): StoryMap;
 
+/**
+ * Lint mode: compile + inspect story structure without producing output.
+ * Surfaces broken links, dead ends, orphans, and compilation diagnostics.
+ */
+
+interface LintResult {
+    /** Compilation diagnostics (errors and warnings). */
+    diagnostics: Diagnostic[];
+    /** Compilation statistics. */
+    stats: CompileStats;
+    /** Story format name from StoryData (e.g. "SugarCube"). */
+    formatName: string;
+    /** Story format version from StoryData (e.g. "2.37.3"). */
+    formatVersion: string;
+    /** The configured start passage name. */
+    start: string;
+    /** Total passage count. */
+    passages: number;
+    /** Story passage count (excludes StoryData, StoryTitle, scripts, etc.). */
+    storyPassages: number;
+    /** Info/special passage count. */
+    infoPassages: number;
+    /** Broken links: link targets that don't exist as passages. */
+    brokenLinks: BrokenLink[];
+    /** Story passages with no outgoing links. */
+    deadEnds: string[];
+    /** Story passages that no other passage links to. */
+    orphans: string[];
+}
+/**
+ * Lint a story: compile without output rendering, then inspect structure.
+ * Uses JSON output mode internally to avoid format resolution.
+ */
+declare function lint(options: Omit<CompileOptions, 'outputMode'>): Promise<LintResult>;
+/**
+ * Format a lint result as a human-readable report string.
+ */
+declare function formatLintReport(result: LintResult): string;
+
 /**
  * Passage helpers and output methods.
  * Ported from passage.go / passagedata.go.
@@ -373,4 +412,4 @@ declare function resolveRemoteFormat(name: string, version: string, indices?: st
 /** Discover all cached remote formats. Returns a Map like discoverFormats(). */
 declare function discoverCachedFormats(): Map<string, StoryFormatInfo>;
 
-export { type BrokenLink, CONFIG_FILENAME, type CompileOptions, type CompileResult, type CompileStats, type CompileToFileOptions, type Diagnostic, type InlineSource, ItemType, type LexerItem, type OutputMode, type Passage, type PassageMetadata, type SFAIndex, type SFAIndexEntry, type SourceInput, type SourceLocation, type Story, type StoryFormatInfo, type StoryMap, TweeLexer, type TweeTsConfig, TweeTsError, type WatchOptions, applyTagAliases, compile, compileToFile, discoverCachedFormats, discoverFormats, fetchAndCacheFormat, fetchDirectFormat, generateIFID, getCacheDir, getFormatSearchDirs, loadConfig, loadConfigFile, parseFormatJSON, parseSemver, parseTwee, resolveRemoteFormat, scaffoldConfig, semverCompare, storyInspect, tweeLexer, validateConfig, validateIFID, watch };
+export { type BrokenLink, CONFIG_FILENAME, type CompileOptions, type CompileResult, type CompileStats, type CompileToFileOptions, type Diagnostic, type InlineSource, ItemType, type LexerItem, type LintResult, type OutputMode, type Passage, type PassageMetadata, type SFAIndex, type SFAIndexEntry, type SourceInput, type SourceLocation, type Story, type StoryFormatInfo, type StoryMap, TweeLexer, type TweeTsConfig, TweeTsError, type WatchOptions, applyTagAliases, compile, compileToFile, discoverCachedFormats, discoverFormats, fetchAndCacheFormat, fetchDirectFormat, formatLintReport, generateIFID, getCacheDir, getFormatSearchDirs, lint, loadConfig, loadConfigFile, parseFormatJSON, parseSemver, parseTwee, resolveRemoteFormat, scaffoldConfig, semverCompare, storyInspect, tweeLexer, validateConfig, validateIFID, watch };

package/dist/index.d.ts

@@ -261,6 +261,45 @@ interface BrokenLink {
  */
 declare function storyInspect(story: Story): StoryMap;
 
+/**
+ * Lint mode: compile + inspect story structure without producing output.
+ * Surfaces broken links, dead ends, orphans, and compilation diagnostics.
+ */
+
+interface LintResult {
+    /** Compilation diagnostics (errors and warnings). */
+    diagnostics: Diagnostic[];
+    /** Compilation statistics. */
+    stats: CompileStats;
+    /** Story format name from StoryData (e.g. "SugarCube"). */
+    formatName: string;
+    /** Story format version from StoryData (e.g. "2.37.3"). */
+    formatVersion: string;
+    /** The configured start passage name. */
+    start: string;
+    /** Total passage count. */
+    passages: number;
+    /** Story passage count (excludes StoryData, StoryTitle, scripts, etc.). */
+    storyPassages: number;
+    /** Info/special passage count. */
+    infoPassages: number;
+    /** Broken links: link targets that don't exist as passages. */
+    brokenLinks: BrokenLink[];
+    /** Story passages with no outgoing links. */
+    deadEnds: string[];
+    /** Story passages that no other passage links to. */
+    orphans: string[];
+}
+/**
+ * Lint a story: compile without output rendering, then inspect structure.
+ * Uses JSON output mode internally to avoid format resolution.
+ */
+declare function lint(options: Omit<CompileOptions, 'outputMode'>): Promise<LintResult>;
+/**
+ * Format a lint result as a human-readable report string.
+ */
+declare function formatLintReport(result: LintResult): string;
+
 /**
  * Passage helpers and output methods.
  * Ported from passage.go / passagedata.go.
@@ -373,4 +412,4 @@ declare function resolveRemoteFormat(name: string, version: string, indices?: st
 /** Discover all cached remote formats. Returns a Map like discoverFormats(). */
 declare function discoverCachedFormats(): Map<string, StoryFormatInfo>;
 
-export { type BrokenLink, CONFIG_FILENAME, type CompileOptions, type CompileResult, type CompileStats, type CompileToFileOptions, type Diagnostic, type InlineSource, ItemType, type LexerItem, type OutputMode, type Passage, type PassageMetadata, type SFAIndex, type SFAIndexEntry, type SourceInput, type SourceLocation, type Story, type StoryFormatInfo, type StoryMap, TweeLexer, type TweeTsConfig, TweeTsError, type WatchOptions, applyTagAliases, compile, compileToFile, discoverCachedFormats, discoverFormats, fetchAndCacheFormat, fetchDirectFormat, generateIFID, getCacheDir, getFormatSearchDirs, loadConfig, loadConfigFile, parseFormatJSON, parseSemver, parseTwee, resolveRemoteFormat, scaffoldConfig, semverCompare, storyInspect, tweeLexer, validateConfig, validateIFID, watch };
+export { type BrokenLink, CONFIG_FILENAME, type CompileOptions, type CompileResult, type CompileStats, type CompileToFileOptions, type Diagnostic, type InlineSource, ItemType, type LexerItem, type LintResult, type OutputMode, type Passage, type PassageMetadata, type SFAIndex, type SFAIndexEntry, type SourceInput, type SourceLocation, type Story, type StoryFormatInfo, type StoryMap, TweeLexer, type TweeTsConfig, TweeTsError, type WatchOptions, applyTagAliases, compile, compileToFile, discoverCachedFormats, discoverFormats, fetchAndCacheFormat, fetchDirectFormat, formatLintReport, generateIFID, getCacheDir, getFormatSearchDirs, lint, loadConfig, loadConfigFile, parseFormatJSON, parseSemver, parseTwee, resolveRemoteFormat, scaffoldConfig, semverCompare, storyInspect, tweeLexer, validateConfig, validateIFID, watch };

package/dist/index.js

@@ -258,8 +258,21 @@ function quote(s) {
 }
 
 // src/story.ts
+var passageIndex = /* @__PURE__ */ new WeakMap();
+function getIndex(story) {
+  let index = passageIndex.get(story);
+  if (!index) {
+    index = /* @__PURE__ */ new Map();
+    for (let i = 0; i < story.passages.length; i++) {
+      const passage = story.passages[i];
+      if (passage) index.set(passage.name, i);
+    }
+    passageIndex.set(story, index);
+  }
+  return index;
+}
 function createStory() {
-  return {
+  const story = {
     name: "",
     ifid: "",
     passages: [],
@@ -275,16 +288,17 @@ function createStory() {
       zoom: 1
     }
   };
+  passageIndex.set(story, /* @__PURE__ */ new Map());
+  return story;
 }
 function storyHas(story, name) {
-  return story.passages.some((p) => p.name === name);
-}
-function storyIndex(story, name) {
-  return story.passages.findIndex((p) => p.name === name);
+  return getIndex(story).has(name);
 }
 function storyAppend(story, p, diagnostics) {
-  const i = storyIndex(story, p.name);
+  const index = getIndex(story);
+  const i = index.get(p.name) ?? -1;
   if (i === -1) {
+    index.set(p.name, story.passages.length);
     story.passages.push(p);
   } else {
     diagnostics.push({
@@ -295,9 +309,15 @@ function storyAppend(story, p, diagnostics) {
   }
 }
 function storyPrepend(story, p, diagnostics) {
-  const i = storyIndex(story, p.name);
+  const index = getIndex(story);
+  const i = index.get(p.name) ?? -1;
   if (i === -1) {
     story.passages.unshift(p);
+    index.clear();
+    for (let j = 0; j < story.passages.length; j++) {
+      const passage = story.passages[j];
+      if (passage) index.set(passage.name, j);
+    }
   } else {
     diagnostics.push({
       level: "warning",
@@ -587,11 +607,15 @@ function watchFilesystem(pathnames, outFilename, callback) {
   const watchers = [];
   let buildTimer = null;
   const BUILD_DEBOUNCE = 500;
-  function scheduleBuild() {
+  const pendingFiles = /* @__PURE__ */ new Set();
+  function scheduleBuild(changedFile) {
+    if (changedFile) pendingFiles.add(changedFile);
     if (buildTimer) clearTimeout(buildTimer);
     buildTimer = setTimeout(() => {
       buildTimer = null;
-      callback();
+      const files = pendingFiles.size > 0 ? new Set(pendingFiles) : void 0;
+      pendingFiles.clear();
+      callback(files);
     }, BUILD_DEBOUNCE);
   }
   for (const pathname of pathnames) {
@@ -601,7 +625,8 @@ function watchFilesystem(pathnames, outFilename, callback) {
         const abs = resolve(pathname, filename);
         if (abs === absOutFile) return;
         if (isKnownFileType(filename)) {
-          scheduleBuild();
+          const rel = relative(process.cwd(), abs);
+          scheduleBuild(rel || abs);
         }
       });
       watchers.push(watcher);
@@ -860,6 +885,7 @@ function readFormatSource(format) {
 
 // src/loader.ts
 import { basename } from "path";
+import { statSync as statSync3 } from "fs";
 
 // src/lexer.ts
 var EOF = -1;
@@ -1383,54 +1409,182 @@ function loadInlineSources(story, sources, opts, diagnostics) {
     }
   }
 }
-function loadTwee(story, filename, opts, diagnostics) {
+function parseTweeFile(filename, opts) {
   const source = readUTF8(filename);
   const result = parseTwee(source, {
     filename,
     trim: opts.trim ?? true,
     twee2Compat: opts.twee2Compat ?? false
   });
-  diagnostics.push(...result.diagnostics);
-  for (const p of result.passages) {
-    storyAdd(story, p, diagnostics);
-  }
+  return { passages: result.passages, diagnostics: [...result.diagnostics] };
 }
-function loadTagged(story, tag, filename, diagnostics) {
+function parseTaggedFile(tag, filename) {
   const source = readUTF8(filename);
-  storyAdd(story, { name: basename(filename), tags: [tag], text: source }, diagnostics);
+  return { passages: [{ name: basename(filename), tags: [tag], text: source }], diagnostics: [] };
 }
-function loadMedia(story, tag, filename, diagnostics) {
+function parseMediaFile(tag, filename) {
   const source = readBase64(filename);
   const name = baseNameWithoutExt(filename);
-  storyAdd(
-    story,
-    {
-      name,
-      tags: [tag],
-      text: `data:${mediaTypeFromFilename(filename)};base64,${source}`
-    },
-    diagnostics
-  );
+  return {
+    passages: [{ name, tags: [tag], text: `data:${mediaTypeFromFilename(filename)};base64,${source}` }],
+    diagnostics: []
+  };
 }
-function loadFont(story, filename, diagnostics) {
+function parseFontFile(filename) {
   const source = readBase64(filename);
   const name = basename(filename);
   const family = baseNameWithoutExt(filename);
   const ext = normalizedFileExt(filename);
   const mediaType = mediaTypeFromExt(ext);
   const hint = fontFormatHint(ext);
-  storyAdd(
-    story,
-    {
-      name,
-      tags: ["stylesheet"],
-      text: `@font-face {
+  return {
+    passages: [
+      {
+        name,
+        tags: ["stylesheet"],
+        text: `@font-face {
 	font-family: "${family}";
 	src: url("data:${mediaType};base64,${source}") format("${hint}");
 }`
-    },
-    diagnostics
-  );
+      }
+    ],
+    diagnostics: []
+  };
+}
+function parseFile(filename, opts) {
+  const ext = normalizedFileExt(filename);
+  switch (ext) {
+    case "tw":
+    case "twee":
+      return parseTweeFile(filename, opts);
+    case "tw2":
+    case "twee2":
+      return parseTweeFile(filename, { ...opts, twee2Compat: true });
+    case "css":
+      return parseTaggedFile("stylesheet", filename);
+    case "js":
+      return parseTaggedFile("script", filename);
+    case "otf":
+    case "ttf":
+    case "woff":
+    case "woff2":
+      return parseFontFile(filename);
+    case "gif":
+    case "jpeg":
+    case "jpg":
+    case "png":
+    case "svg":
+    case "tif":
+    case "tiff":
+    case "webp":
+      return parseMediaFile("Twine.image", filename);
+    case "aac":
+    case "flac":
+    case "m4a":
+    case "mp3":
+    case "oga":
+    case "ogg":
+    case "opus":
+    case "wav":
+    case "wave":
+    case "weba":
+      return parseMediaFile("Twine.audio", filename);
+    case "mp4":
+    case "ogv":
+    case "webm":
+      return parseMediaFile("Twine.video", filename);
+    case "vtt":
+      return parseMediaFile("Twine.vtt", filename);
+    default:
+      return void 0;
+  }
+}
+function loadTwee(story, filename, opts, diagnostics) {
+  const result = parseTweeFile(filename, opts);
+  diagnostics.push(...result.diagnostics);
+  for (const p of result.passages) {
+    storyAdd(story, p, diagnostics);
+  }
+}
+function loadTagged(story, tag, filename, diagnostics) {
+  const result = parseTaggedFile(tag, filename);
+  for (const p of result.passages) {
+    storyAdd(story, p, diagnostics);
+  }
+}
+function loadMedia(story, tag, filename, diagnostics) {
+  const result = parseMediaFile(tag, filename);
+  for (const p of result.passages) {
+    storyAdd(story, p, diagnostics);
+  }
+}
+function loadFont(story, filename, diagnostics) {
+  const result = parseFontFile(filename);
+  for (const p of result.passages) {
+    storyAdd(story, p, diagnostics);
+  }
+}
+function loadSourcesCached(story, filenames, opts, diagnostics, processedFiles, cache, changedFiles) {
+  const currentFiles = /* @__PURE__ */ new Set();
+  for (const filename of filenames) {
+    if (processedFiles.has(filename)) {
+      diagnostics.push({ level: "warning", message: `load ${filename}: Skipping duplicate.` });
+      continue;
+    }
+    currentFiles.add(filename);
+    const cached = cache.get(filename);
+    if (changedFiles && cached && !changedFiles.has(filename)) {
+      diagnostics.push(...cached.diagnostics);
+      for (const p of cached.passages) {
+        storyAdd(story, p, diagnostics);
+      }
+      processedFiles.add(filename);
+      continue;
+    }
+    let mtimeMs;
+    try {
+      mtimeMs = statSync3(filename).mtimeMs;
+    } catch {
+      continue;
+    }
+    if (cached && cached.mtimeMs === mtimeMs) {
+      diagnostics.push(...cached.diagnostics);
+      for (const p of cached.passages) {
+        storyAdd(story, p, diagnostics);
+      }
+      processedFiles.add(filename);
+      continue;
+    }
+    try {
+      const result = parseFile(filename, opts);
+      if (!result) continue;
+      cache.set(filename, {
+        mtimeMs,
+        passages: result.passages,
+        diagnostics: result.diagnostics
+      });
+      diagnostics.push(...result.diagnostics);
+      for (const p of result.passages) {
+        storyAdd(story, p, diagnostics);
+      }
+    } catch (e) {
+      diagnostics.push({
+        level: "error",
+        message: `load ${filename}: ${e instanceof Error ? e.message : String(e)}`,
+        file: filename
+      });
+      continue;
+    }
+    processedFiles.add(filename);
+  }
+  for (const key of cache.keys()) {
+    if (!currentFiles.has(key)) {
+      cache.delete(key);
+    }
+  }
+  if (story.name !== "" && !story.passages.some((p) => p.name === "StoryTitle")) {
+    storyPrepend(story, { name: "StoryTitle", tags: [], text: story.name }, diagnostics);
+  }
 }
 
 // src/version.ts
@@ -1699,7 +1853,7 @@ function modifyHead(html, modulePaths, headFile, diagnostics) {
 }
 
 // src/remote-formats.ts
-import { mkdirSync, readFileSync as readFileSync3, writeFileSync, existsSync, readdirSync as readdirSync3, statSync as statSync3 } from "fs";
+import { mkdirSync, readFileSync as readFileSync3, writeFileSync, existsSync, readdirSync as readdirSync3, statSync as statSync4 } from "fs";
 import { join as join4 } from "path";
 import { homedir as homedir2 } from "os";
 var DEFAULT_SFA_INDICES = [
@@ -1911,7 +2065,7 @@ function discoverCachedFormats() {
   for (const name of names) {
     const nameDir = join4(cacheDir, name);
     try {
-      if (!statSync3(nameDir).isDirectory()) continue;
+      if (!statSync4(nameDir).isDirectory()) continue;
     } catch {
       continue;
     }
@@ -1952,11 +2106,12 @@ async function compileToFile(options) {
 }
 async function watch(options) {
   const controller = new AbortController();
+  const cache = /* @__PURE__ */ new Map();
   const filePaths = options.sources.filter((s) => typeof s === "string");
   const modulePaths = options.modules ?? [];
   const allPaths = [...filePaths, ...modulePaths];
-  const handle = watchFilesystem(allPaths, options.outFile, () => {
-    buildOutput(options).then((result) => {
+  const handle = watchFilesystem(allPaths, options.outFile, (changedFiles) => {
+    buildOutput(options, cache, changedFiles).then((result) => {
       writeFileSync2(options.outFile, result.output, "utf-8");
       options.onBuild?.(result);
     }).catch((e) => {
@@ -1966,7 +2121,7 @@ async function watch(options) {
   controller.signal.addEventListener("abort", () => handle.close());
   return controller;
 }
-async function buildOutput(options) {
+async function buildOutput(options, cache, changedFiles) {
   const diagnostics = [];
   const outputMode = options.outputMode ?? "html";
   const trim = options.trim ?? true;
@@ -1987,7 +2142,11 @@ async function buildOutput(options) {
   const sourceFilenames = getFilenames(filePaths);
   const story = createStory();
   const processedFiles = /* @__PURE__ */ new Set();
-  loadSources(story, sourceFilenames, { trim, twee2Compat }, diagnostics, processedFiles);
+  if (cache) {
+    loadSourcesCached(story, sourceFilenames, { trim, twee2Compat }, diagnostics, processedFiles, cache, changedFiles);
+  } else {
+    loadSources(story, sourceFilenames, { trim, twee2Compat }, diagnostics, processedFiles);
+  }
   loadInlineSources(story, inlineSources, { trim, twee2Compat }, diagnostics);
   if (options.tagAliases) {
     story.passages = applyTagAliases(story.passages, options.tagAliases);
@@ -2227,6 +2386,69 @@ function storyInspect(story) {
   };
 }
 
+// src/lint.ts
+async function lint(options) {
+  const result = await compile({ ...options, outputMode: "json" });
+  const map = storyInspect(result.story);
+  return {
+    diagnostics: result.diagnostics,
+    stats: result.stats,
+    formatName: result.story.twine2.format,
+    formatVersion: result.story.twine2.formatVersion,
+    start: map.start,
+    passages: map.passages.length,
+    storyPassages: map.storyPassages.length,
+    infoPassages: map.infoPassages.length,
+    brokenLinks: map.brokenLinks,
+    deadEnds: map.deadEnds,
+    orphans: map.orphans
+  };
+}
+function formatLintReport(result) {
+  const lines = [];
+  const formatStr = result.formatName ? `${result.formatName}${result.formatVersion ? " " + result.formatVersion : ""}` : "unknown";
+  lines.push(`Format: ${formatStr}`);
+  lines.push(
+    `Passages: ${result.passages} total (${result.storyPassages} story, ${result.infoPassages} info), ${result.stats.words.toLocaleString()} words, ${result.stats.files.length} files`
+  );
+  lines.push(`Start: ${result.start}`);
+  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)`);
+    }
+  }
+  if (result.deadEnds.length > 0) {
+    lines.push("");
+    lines.push(`Dead ends (${result.deadEnds.length}): ${result.deadEnds.join(", ")}`);
+  }
+  if (result.orphans.length > 0) {
+    lines.push("");
+    lines.push(`Orphans (${result.orphans.length}): ${result.orphans.join(", ")}`);
+  }
+  const errors = result.diagnostics.filter((d) => d.level === "error");
+  const warnings = result.diagnostics.filter((d) => d.level === "warning");
+  if (errors.length > 0 || warnings.length > 0) {
+    lines.push("");
+    lines.push(`Diagnostics: ${errors.length} error(s), ${warnings.length} warning(s)`);
+    for (const d of errors) {
+      lines.push(`  error: ${d.message}`);
+    }
+    for (const d of warnings) {
+      lines.push(`  warning: ${d.message}`);
+    }
+  }
+  lines.push("");
+  const hasErrors = errors.length > 0 || result.brokenLinks.length > 0;
+  if (hasErrors) {
+    lines.push("Lint failed.");
+  } else {
+    lines.push("Lint passed.");
+  }
+  return lines.join("\n");
+}
+
 // src/config.ts
 import { readFileSync as readFileSync4, existsSync as existsSync2 } from "fs";
 import { join as join5 } from "path";
@@ -2338,9 +2560,11 @@ export {
   discoverFormats,
   fetchAndCacheFormat,
   fetchDirectFormat,
+  formatLintReport,
   generateIFID,
   getCacheDir,
   getFormatSearchDirs,
+  lint,
   loadConfig,
   loadConfigFile,
   parseFormatJSON,