@rohal12/twee-ts 1.6.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

@@ -2386,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";
@@ -2497,9 +2560,11 @@ export {
   discoverFormats,
   fetchAndCacheFormat,
   fetchDirectFormat,
+  formatLintReport,
   generateIFID,
   getCacheDir,
   getFormatSearchDirs,
+  lint,
   loadConfig,
   loadConfigFile,
   parseFormatJSON,