@rohal12/twee-ts 1.6.0 → 1.8.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.
@@ -372,5 +411,21 @@ declare function fetchDirectFormat(url: string): Promise<StoryFormatInfo>;
 declare function resolveRemoteFormat(name: string, version: string, indices?: string[], urls?: string[]): Promise<StoryFormatInfo | undefined>;
 /** Discover all cached remote formats. Returns a Map like discoverFormats(). */
 declare function discoverCachedFormats(): Map<string, StoryFormatInfo>;
+/** Info about a cached format entry with size and modification date. */
+interface CachedFormatEntry {
+    readonly name: string;
+    readonly version: string;
+    readonly sizeBytes: number;
+    readonly modifiedAt: Date;
+}
+/** List all cached formats with size and modification date. */
+declare function listCachedFormats(): readonly CachedFormatEntry[];
+/** Clear all cached formats, or only those matching a given name. Returns the number of entries removed. */
+declare function clearCachedFormats(name?: string): number;
+/** Get total cache size in bytes and format count. */
+declare function getCacheSize(): {
+    totalBytes: number;
+    count: number;
+};
 
-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 CachedFormatEntry, 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, clearCachedFormats, compile, compileToFile, discoverCachedFormats, discoverFormats, fetchAndCacheFormat, fetchDirectFormat, formatLintReport, generateIFID, getCacheDir, getCacheSize, getFormatSearchDirs, lint, listCachedFormats, 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.
@@ -372,5 +411,21 @@ declare function fetchDirectFormat(url: string): Promise<StoryFormatInfo>;
 declare function resolveRemoteFormat(name: string, version: string, indices?: string[], urls?: string[]): Promise<StoryFormatInfo | undefined>;
 /** Discover all cached remote formats. Returns a Map like discoverFormats(). */
 declare function discoverCachedFormats(): Map<string, StoryFormatInfo>;
+/** Info about a cached format entry with size and modification date. */
+interface CachedFormatEntry {
+    readonly name: string;
+    readonly version: string;
+    readonly sizeBytes: number;
+    readonly modifiedAt: Date;
+}
+/** List all cached formats with size and modification date. */
+declare function listCachedFormats(): readonly CachedFormatEntry[];
+/** Clear all cached formats, or only those matching a given name. Returns the number of entries removed. */
+declare function clearCachedFormats(name?: string): number;
+/** Get total cache size in bytes and format count. */
+declare function getCacheSize(): {
+    totalBytes: number;
+    count: number;
+};
 
-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 CachedFormatEntry, 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, clearCachedFormats, compile, compileToFile, discoverCachedFormats, discoverFormats, fetchAndCacheFormat, fetchDirectFormat, formatLintReport, generateIFID, getCacheDir, getCacheSize, getFormatSearchDirs, lint, listCachedFormats, loadConfig, loadConfigFile, parseFormatJSON, parseSemver, parseTwee, resolveRemoteFormat, scaffoldConfig, semverCompare, storyInspect, tweeLexer, validateConfig, validateIFID, watch };

package/dist/index.js

@@ -1853,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 statSync4 } from "fs";
+import { mkdirSync, readFileSync as readFileSync3, writeFileSync, existsSync, readdirSync as readdirSync3, statSync as statSync4, rmSync } from "fs";
 import { join as join4 } from "path";
 import { homedir as homedir2 } from "os";
 var DEFAULT_SFA_INDICES = [
@@ -2084,6 +2084,75 @@ function discoverCachedFormats() {
   }
   return formats;
 }
+function listCachedFormats() {
+  const cacheDir = getCacheDir();
+  const entries = [];
+  try {
+    if (!existsSync(cacheDir)) return entries;
+  } catch {
+    return entries;
+  }
+  let names;
+  try {
+    names = readdirSync3(cacheDir);
+  } catch {
+    return entries;
+  }
+  for (const name of names) {
+    const nameDir = join4(cacheDir, name);
+    try {
+      if (!statSync4(nameDir).isDirectory()) continue;
+    } catch {
+      continue;
+    }
+    let versions;
+    try {
+      versions = readdirSync3(nameDir);
+    } catch {
+      continue;
+    }
+    for (const version of versions) {
+      const formatPath = join4(nameDir, version, "format.js");
+      try {
+        const stat = statSync4(formatPath);
+        entries.push({
+          name,
+          version,
+          sizeBytes: stat.size,
+          modifiedAt: stat.mtime
+        });
+      } catch {
+      }
+    }
+  }
+  return entries;
+}
+function clearCachedFormats(name) {
+  const cacheDir = getCacheDir();
+  if (!existsSync(cacheDir)) return 0;
+  if (!name) {
+    const entries = listCachedFormats();
+    const count2 = entries.length;
+    rmSync(cacheDir, { recursive: true, force: true });
+    return count2;
+  }
+  const nameDir = join4(cacheDir, name);
+  if (!existsSync(nameDir)) return 0;
+  let versions;
+  try {
+    versions = readdirSync3(nameDir);
+  } catch {
+    return 0;
+  }
+  const count = versions.length;
+  rmSync(nameDir, { recursive: true, force: true });
+  return count;
+}
+function getCacheSize() {
+  const entries = listCachedFormats();
+  const totalBytes = entries.reduce((sum, e) => sum + e.sizeBytes, 0);
+  return { totalBytes, count: entries.length };
+}
 
 // src/compiler.ts
 var CREATOR_NAME3 = "Twee-ts";
@@ -2386,6 +2455,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";
@@ -2491,15 +2623,20 @@ export {
   TweeLexer,
   TweeTsError,
   applyTagAliases,
+  clearCachedFormats,
   compile,
   compileToFile,
   discoverCachedFormats,
   discoverFormats,
   fetchAndCacheFormat,
   fetchDirectFormat,
+  formatLintReport,
   generateIFID,
   getCacheDir,
+  getCacheSize,
   getFormatSearchDirs,
+  lint,
+  listCachedFormats,
   loadConfig,
   loadConfigFile,
   parseFormatJSON,