politty 0.4.11 → 0.4.13

package/dist/docs/index.d.cts

@@ -1,5 +1,4 @@
-import { A as SubCommandValue, c as ArgsSchema, p as Example, s as AnyCommand } from "../arg-registry-BDybpyo5.cjs";
-import { n as ResolvedFieldMeta, t as ExtractedFields } from "../schema-extractor-RainqdRn.cjs";
+import { N as SubCommandValue, R as ExtractedFields, h as Example, l as AnyCommand, u as ArgsSchema, z as ResolvedFieldMeta } from "../arg-registry-CeIRoLaB.cjs";
 import { z } from "zod";
 import * as fs from "node:fs";
 
@@ -431,6 +430,12 @@ type FormatterFunction = (content: string) => string | Promise<string>;
  * Environment variable name for update mode
  */
 declare const UPDATE_GOLDEN_ENV = "POLITTY_DOCS_UPDATE";
+/**
+ * Environment variable name for doctor mode.
+ * When enabled alone, detects and reports missing section markers (read-only).
+ * When combined with POLITTY_DOCS_UPDATE=true, auto-inserts missing markers.
+ */
+declare const DOCTOR_ENV = "POLITTY_DOCS_DOCTOR";
 /**
  * All section types in rendering order
  */
@@ -697,5 +702,5 @@ type CommandCategory = {
  */
 declare function renderCommandIndex(command: AnyCommand, categories: CommandCategory[], options?: CommandIndexOptions): Promise<string>;
 //#endregion
-export { type ArgsShape, type ArgsTableOptions, type ArgumentsRenderContext, type ArgumentsRenderFunction, type CommandCategory, type CommandIndexOptions, type CommandInfo, type DefaultRendererOptions, type DeleteFileFs, type ExampleCommandConfig, type ExampleConfig, type ExampleExecutionResult, type ExamplesRenderContext, type ExamplesRenderFunction, type ExamplesRenderOptions, type FileConfig, type FileMapping, type FormatterFunction, GLOBAL_OPTIONS_MARKER_PREFIX, type GenerateDocConfig, type GenerateDocResult, type HeadingLevel, INDEX_MARKER_PREFIX, type OptionsRenderContext, type OptionsRenderFunction, type PathConfig, ROOT_FOOTER_MARKER_PREFIX, ROOT_HEADER_MARKER_PREFIX, type RenderContentOptions, type RenderFunction, type RootCommandInfo, type RootDocConfig, SECTION_MARKER_PREFIX, SECTION_TYPES, type SectionRenderFunction, type SectionType, type SimpleRenderContext, type SimpleRenderFunction, type SubCommandInfo, type SubcommandsRenderContext, type SubcommandsRenderFunction, type SubcommandsRenderOptions, UPDATE_GOLDEN_ENV, assertDocMatch, buildCommandInfo, collectAllCommands, compareWithExisting, createCommandRenderer, defaultRenderers, executeExamples, formatDiff, generateDoc, globalOptionsEndMarker, globalOptionsStartMarker, indexEndMarker, indexStartMarker, initDocFile, renderArgsTable, renderArgumentsList, renderArgumentsListFromArray, renderArgumentsTable, renderArgumentsTableFromArray, renderCommandIndex, renderExamplesDefault, renderOptionsList, renderOptionsListFromArray, renderOptionsTable, renderOptionsTableFromArray, renderSubcommandsTable, renderSubcommandsTableFromArray, renderUsage, resolveLazyCommand, rootFooterEndMarker, rootFooterStartMarker, rootHeaderEndMarker, rootHeaderStartMarker, sectionEndMarker, sectionStartMarker, writeFile };
+export { type ArgsShape, type ArgsTableOptions, type ArgumentsRenderContext, type ArgumentsRenderFunction, type CommandCategory, type CommandIndexOptions, type CommandInfo, DOCTOR_ENV, type DefaultRendererOptions, type DeleteFileFs, type ExampleCommandConfig, type ExampleConfig, type ExampleExecutionResult, type ExamplesRenderContext, type ExamplesRenderFunction, type ExamplesRenderOptions, type FileConfig, type FileMapping, type FormatterFunction, GLOBAL_OPTIONS_MARKER_PREFIX, type GenerateDocConfig, type GenerateDocResult, type HeadingLevel, INDEX_MARKER_PREFIX, type OptionsRenderContext, type OptionsRenderFunction, type PathConfig, ROOT_FOOTER_MARKER_PREFIX, ROOT_HEADER_MARKER_PREFIX, type RenderContentOptions, type RenderFunction, type RootCommandInfo, type RootDocConfig, SECTION_MARKER_PREFIX, SECTION_TYPES, type SectionRenderFunction, type SectionType, type SimpleRenderContext, type SimpleRenderFunction, type SubCommandInfo, type SubcommandsRenderContext, type SubcommandsRenderFunction, type SubcommandsRenderOptions, UPDATE_GOLDEN_ENV, assertDocMatch, buildCommandInfo, collectAllCommands, compareWithExisting, createCommandRenderer, defaultRenderers, executeExamples, formatDiff, generateDoc, globalOptionsEndMarker, globalOptionsStartMarker, indexEndMarker, indexStartMarker, initDocFile, renderArgsTable, renderArgumentsList, renderArgumentsListFromArray, renderArgumentsTable, renderArgumentsTableFromArray, renderCommandIndex, renderExamplesDefault, renderOptionsList, renderOptionsListFromArray, renderOptionsTable, renderOptionsTableFromArray, renderSubcommandsTable, renderSubcommandsTableFromArray, renderUsage, resolveLazyCommand, rootFooterEndMarker, rootFooterStartMarker, rootHeaderEndMarker, rootHeaderStartMarker, sectionEndMarker, sectionStartMarker, writeFile };
 //# sourceMappingURL=index.d.cts.map

package/dist/docs/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/executor/subcommand-router.ts","../../src/docs/render-args.ts","../../src/docs/types.ts","../../src/docs/default-renderers.ts","../../src/docs/doc-comparator.ts","../../src/docs/doc-generator.ts","../../src/docs/example-executor.ts","../../src/docs/golden-test.ts","../../src/docs/render-index.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/executor/subcommand-router.ts","../../src/docs/render-args.ts","../../src/docs/types.ts","../../src/docs/default-renderers.ts","../../src/docs/doc-comparator.ts","../../src/docs/doc-generator.ts","../../src/docs/example-executor.ts","../../src/docs/golden-test.ts","../../src/docs/render-index.ts"],"mappings":";;;;;;;;;AASA;;iBAAsB,kBAAA,CAAmB,GAAA,EAAK,eAAA,GAAkB,OAAA,CAAQ,UAAA;;;;;;;KCD5D,SAAA,GAAY,MAAA,SAAe,CAAA,CAAE,OAAA;;;;KAK7B,gBAAA;EDJoD,6DCM9D,OAAA;AAAA;;;;;;;;;;AAPF;;;;;;;;;AAKA;;;;;iBAyCgB,eAAA,CAAgB,IAAA,EAAM,SAAA,EAAW,OAAA,GAAU,gBAAA;;;;KCjD/C,YAAA;AFIZ;;;AAAA,KECY,mBAAA;EFD4D,4DEGtE,YAAA,GAAe,YAAA,EFHsD;EEKrE,QAAA;AAAA;;;;UAMe,WAAA;EFXiE;EEahF,IAAA;;EAEA,WAAA;EDhBU;ECkBV,eAAA;;EAEA,WAAA;EDpBsB;ECsBtB,KAAA;EDtBuC;ECwBvC,cAAA,EAAgB,iBAAA;EDxB8B;EC0B9C,OAAA,EAAS,iBAAA;EDrBiB;ECuB1B,WAAA,EAAa,cAAA;EDrBb;ECuBA,SAAA,EAAW,eAAA;EDgBG;ECdd,OAAA,EAAS,UAAA;;EAET,KAAA;EDYoC;ECVpC,QAAA;EDUyD;ECRzD,OAAA,GAAU,MAAA;EDQ+D;ECNzE,QAAA,GAAW,OAAA;;EAEX,cAAA,GAAiB,sBAAA;;EAEjB,WAAA;EA/CsB;EAiDtB,gBAAA;AAAA;;AA5CF;;UAkDiB,cAAA;EAhDY;EAkD3B,IAAA;EAlDe;EAoDf,WAAA;EAlDQ;EAoDR,QAAA;AAAA;;;;UAMe,sBAAA;EApCF;EAsCb,GAAA;EAlCS;EAoCT,IAAA;EA5BW;EA8BX,cAAA;EA5BuC;EA8BvC,MAAA;EA1DA;EA4DA,MAAA;EAxDA;EA0DA,OAAA;AAAA;;;;;UAOe,oBAAA;EAvDF;EAyDb,IAAA,gBAAoB,OAAA;EAvDT;EAyDX,OAAA,gBAAuB,OAAA;AAAA;;;;;;;;;;;;;KAeb,aAAA,GAAgB,MAAA,SAAe,oBAAA;;;;KAK/B,cAAA,IAAkB,IAAA,EAAM,WAAA;;;;;AA3CpC;;;KAoDY,qBAAA,IAAyB,cAAA,UAAwB,IAAA,EAAM,WAAA;;;;UAKlD,oBAAA;EA/Cf;EAiDA,KAAA;EA/CO;EAiDP,WAAA;AAAA;;;;UAMe,oBAAA;EA9CK;EAgDpB,OAAA,EAAS,iBAAA;EA9Cc;EAgDvB,MAAA,GAAS,OAAA,EAAS,iBAAA,IAAqB,IAAA,GAAO,oBAAA;EAhDhB;EAkD9B,OAAA;EAnCuB;EAqCvB,IAAA,EAAM,WAAA;AAAA;AAAA,KAEI,qBAAA,IAAyB,OAAA,EAAS,oBAAA;AAlC9C;;;AAAA,UAuCiB,sBAAA;EAvC8B;EAyC7C,IAAA,EAAM,iBAAA;EAhCyB;EAkC/B,MAAA,GAAS,IAAA,EAAM,iBAAA,IAAqB,IAAA,GAAO,oBAAA;EAlCiC;EAoC5E,OAAA;EApCiE;EAsCjE,IAAA,EAAM,WAAA;AAAA;AAAA,KAEI,uBAAA,IAA2B,OAAA,EAAS,sBAAA;AAnChD;;;AAAA,UAwCiB,wBAAA;EApCJ;EAsCX,eAAA;EAhCmC;EAkCnC,WAAA;AAAA;;;;UAMe,wBAAA;EAhCE;EAkCjB,WAAA,EAAa,cAAA;EAxCJ;EA0CT,MAAA,GAAS,WAAA,EAAa,cAAA,IAAkB,IAAA,GAAO,wBAAA;EAxC7B;EA0ClB,OAAA;EA1C8C;EA4C9C,IAAA,EAAM,WAAA;AAAA;AAAA,KAEI,yBAAA,IAA6B,OAAA,EAAS,wBAAA;;;;UAKjC,qBAAA;EA7CgB;EA+C/B,WAAA;EA/C4C;EAiD5C,UAAA;EA5Ce;EA8Cf,aAAA;AAAA;;;;UAMe,qBAAA;EA5CE;EA8CjB,QAAA,EAAU,OAAA;EApDV;EAsDA,OAAA,GAAU,sBAAA;EApDV;EAsDA,MAAA,GACE,QAAA,EAAU,OAAA,IACV,OAAA,GAAU,sBAAA,IACV,IAAA,GAAO,qBAAA;EAzDA;EA4DT,OAAA;EA5DoC;EA8DpC,IAAA,EAAM,WAAA;AAAA;AAAA,KAEI,sBAAA,IAA0B,OAAA,EAAS,qBAAA;;;AA1D/C;UA+DiB,mBAAA;;EAEf,OAAA;EAjEoE;EAmEpE,OAAA;EA9DuC;EAgEvC,IAAA,EAAM,WAAA;AAAA;AAAA,KAEI,oBAAA,IAAwB,OAAA,EAAS,mBAAA;AAxD7C;;;AAAA,UA6DiB,sBAAA;EAzDO;EA2DtB,YAAA,GAAe,YAAA;EAvDT;EAyDN,WAAA;EAzDiB;EA2DjB,eAAA;EAjEa;EAmEb,wBAAA;EAjEsB;EAmEtB,iBAAA,GAAoB,oBAAA;EAnE2B;EAqE/C,WAAA,GAAc,oBAAA;EAnEd;EAqEA,eAAA,GAAkB,uBAAA;EAnEZ;EAqEN,aAAA,GAAgB,qBAAA;EArEC;EAuEjB,iBAAA,GAAoB,yBAAA;EArEe;EAuEnC,WAAA,GAAc,oBAAA;EAvEkC;EAyEhD,YAAA,GAAe,oBAAA;EApEA;EAsEf,cAAA,GAAiB,sBAAA;AAAA;;;;;UAOF,aAAA;EAvEF;EAyEb,IAAA;EAnEoC;;;;EAwEpC,aAAA,GAAgB,SAAA;IAAc,IAAA,EAAM,SAAA;IAAW,OAAA,GAAU,gBAAA;EAAA;EA1DxC;EA4DjB,YAAA,GAAe,YAAA;EAxEf;EA0EA,KAAA,GAAQ,mBAAA;AAAA;;;;;UAOO,eAAA;EA3Eb;EA6EF,KAAA;EA5EE;EA8EF,WAAA;EAzEA;EA2EA,MAAA;EA3EiB;EA6EjB,MAAA;AAAA;;;;;AAtEF;;;;;;;KAoFY,UAAA;EAAwB,IAAA;EAAc,QAAA,GAAW,MAAA;AAAA;;;;UAK5C,UAAA;EA5EA;EA8Ef,QAAA;;EAEA,MAAA,GAAS,cAAA;EAtEW;EAwEpB,KAAA;EApEkB;EAsElB,WAAA;EAlEoB;EAoEpB,QAAA;AAAA;;;;;;;;;;;;;KAeU,WAAA,GAAc,MAAA,oBAA0B,UAAA;;;;UAKnC,iBAAA;EAxFK;EA0FpB,OAAA,EAAS,UAAA;EAxFK;;;;;EA8Fd,OAAA,GAAU,aAAA;EA1F6B;AAOzC;;;EAwFE,IAAA,GAAO,UAAA;EAjF6B;EAmFpC,KAAA,GAAQ,WAAA;EAjFO;EAmFf,QAAA,GAAW,eAAA;EAjFgB;EAmF3B,OAAA;EA5FA;EA8FA,MAAA,GAAS,sBAAA;EAzFO;EA2FhB,SAAA,GAAY,iBAAA;EA3FwB;EA6FpC,QAAA,GAAW,aAAA;EA7F8C;;;;;EAmGzD,cAAA;EA/F2B;AAO7B;;;EA6FE,UAAA,GAAa,UAAA;AAAA;;;;UAME,iBAAA;EA3FT;EA6FN,OAAA;EA/EoB;EAiFpB,KAAA,EAAO,KAAA;IAjF0D,gBAmF/D,IAAA,UAnF8C;IAqF9C,MAAA,4CArF+D;IAuF/D,IAAA;EAAA;EAlFuB;EAqFzB,KAAA;AAAA;;;;;KAOU,iBAAA,IAAqB,OAAA,sBAA6B,OAAA;;;;cAKjD,iBAAA;;;;;AAnEb;cA0Ea,UAAA;;;;cAKA,aAAA;;;;KAeD,WAAA,WAAsB,aAAA;;;;;cAMrB,qBAAA;;;;iBAKG,kBAAA,CAAmB,IAAA,EAAM,WAAA,EAAa,KAAA;;;;iBAOtC,gBAAA,CAAiB,IAAA,EAAM,WAAA,EAAa,KAAA;;;;;cAQvC,4BAAA;;;;iBAKG,wBAAA,CAAA;;;;iBAOA,sBAAA,CAAA;AA1FhB;;;AAAA,cAiGa,yBAAA;AAAA,iBAEG,qBAAA,CAAA;AAAA,iBAIA,mBAAA,CAAA;;;;cAOH,yBAAA;AAAA,iBAEG,qBAAA,CAAA;AAAA,iBAIA,mBAAA,CAAA;;AAhGhB;;;cAwGa,mBAAA;;AAnGb;;iBAwGgB,gBAAA,CAAiB,KAAA;;;AAjGjC;iBAwGgB,cAAA,CAAe,KAAA;;;;;AFngB/B;iBG+BgB,WAAA,CAAY,IAAA,EAAM,WAAA;;;;iBAyBlB,oBAAA,CAAqB,IAAA,EAAM,WAAA;;;;iBAqB3B,mBAAA,CAAoB,IAAA,EAAM,WAAA;;;;;;;;AF9E1C;;;;;;;iBE4JgB,kBAAA,CAAmB,IAAA,EAAM,WAAA;;AFvJzC;;;;;AAyCA;;;;;iBE8JgB,iBAAA,CAAkB,IAAA,EAAM,WAAA;;;;iBAqDxB,sBAAA,CAAuB,IAAA,EAAM,WAAA,EAAa,eAAA;;;;iBAwC1C,2BAAA,CAA4B,OAAA,EAAS,iBAAA;;;;iBAoLrC,0BAAA,CAA2B,OAAA,EAAS,iBAAA;;ADjdpD;;iBCuegB,6BAAA,CAA8B,IAAA,EAAM,iBAAA;;;;iBAqBpC,4BAAA,CAA6B,IAAA,EAAM,iBAAA;;;;iBAkBnC,+BAAA,CACd,WAAA,EAAa,cAAA,IACb,IAAA,EAAM,WAAA,EACN,eAAA;;;;;;;;;;;;;;;;iBAqDc,qBAAA,CACd,QAAA,EAAU,OAAA,IACV,OAAA,GAAU,sBAAA,IACV,IAAA,GAAO,qBAAA;AAAA,iBA2EO,qBAAA,CAAsB,OAAA,GAAS,sBAAA,GAA8B,cAAA;;;;cAiOhE,gBAAA;EDz1BX,yDC21BoB,sBAAA,KAAsB,cAAA,EDz1B1C;8BAEA;;;;;;;;UE9Ce,aAAA;EJGK;EIDpB,KAAA;;EAEA,IAAA;EJDsE;EIGtE,UAAA;AAAA;;;;iBAMc,mBAAA,CAAoB,gBAAA,UAA0B,QAAA,WAAmB,aAAA;;;;iBA6BjE,UAAA,CAAW,QAAA,UAAkB,MAAA;;;AHvC7C;iBG6GgB,SAAA,CAAU,QAAA,UAAkB,OAAA;;;AHxG5C;UGoIiB,YAAA;EACf,UAAA,SAAmB,EAAA,CAAG,UAAA;EACtB,UAAA,SAAmB,EAAA,CAAG,UAAA;AAAA;;;;;;iBC3IF,gBAAA,CACpB,OAAA,EAAS,UAAA,EACT,QAAA,UACA,WAAA,cACC,OAAA,CAAQ,WAAA;;;;;iBAuCW,kBAAA,CACpB,OAAA,EAAS,UAAA,EACT,QAAA,YACC,OAAA,CAAQ,GAAA,SAAY,WAAA;;;;;;AL7CvB;;;;;;iBMIsB,eAAA,CACpB,QAAA,EAAU,OAAA,IACV,MAAA,EAAQ,oBAAA,EACR,WAAA,EAAa,UAAA,EACb,WAAA,cACC,OAAA,CAAQ,sBAAA;;;;;;iBCy3CW,WAAA,CAAY,MAAA,EAAQ,iBAAA,GAAoB,OAAA,CAAQ,iBAAA;;;;;iBAsmBhD,cAAA,CAAe,MAAA,EAAQ,iBAAA,GAAoB,OAAA;;;;;;;;iBA6BjD,WAAA,CACd,MAAA,EAAQ,IAAA,CAAK,iBAAA,qBACb,UAAA,GAAa,YAAA;;;;;;KC3/DH,eAAA;ERZ4B,oDQctC,KAAA,URd4C;EQgB5C,WAAA,URhB8D;EQkB9D,QAAA,YRlBqE;EQoBrE,OAAA;AAAA;;;;;;;APrBF;;;;;;;;;AAKA;;;;;AAyCA;;;;;;;;;;iBOuGsB,kBAAA,CACpB,OAAA,EAAS,UAAA,EACT,UAAA,EAAY,eAAA,IACZ,OAAA,GAAU,mBAAA,GACT,OAAA"}

package/dist/docs/index.d.ts

@@ -1,5 +1,4 @@
-import { A as SubCommandValue, c as ArgsSchema, p as Example, s as AnyCommand } from "../arg-registry-CHmAzJOM.js";
-import { n as ResolvedFieldMeta, t as ExtractedFields } from "../schema-extractor-D1sJW-sc.js";
+import { N as SubCommandValue, R as ExtractedFields, h as Example, l as AnyCommand, u as ArgsSchema, z as ResolvedFieldMeta } from "../arg-registry-6E4C5MTC.js";
 import { z } from "zod";
 import * as fs from "node:fs";
 
@@ -431,6 +430,12 @@ type FormatterFunction = (content: string) => string | Promise<string>;
  * Environment variable name for update mode
  */
 declare const UPDATE_GOLDEN_ENV = "POLITTY_DOCS_UPDATE";
+/**
+ * Environment variable name for doctor mode.
+ * When enabled alone, detects and reports missing section markers (read-only).
+ * When combined with POLITTY_DOCS_UPDATE=true, auto-inserts missing markers.
+ */
+declare const DOCTOR_ENV = "POLITTY_DOCS_DOCTOR";
 /**
  * All section types in rendering order
  */
@@ -697,5 +702,5 @@ type CommandCategory = {
  */
 declare function renderCommandIndex(command: AnyCommand, categories: CommandCategory[], options?: CommandIndexOptions): Promise<string>;
 //#endregion
-export { type ArgsShape, type ArgsTableOptions, type ArgumentsRenderContext, type ArgumentsRenderFunction, type CommandCategory, type CommandIndexOptions, type CommandInfo, type DefaultRendererOptions, type DeleteFileFs, type ExampleCommandConfig, type ExampleConfig, type ExampleExecutionResult, type ExamplesRenderContext, type ExamplesRenderFunction, type ExamplesRenderOptions, type FileConfig, type FileMapping, type FormatterFunction, GLOBAL_OPTIONS_MARKER_PREFIX, type GenerateDocConfig, type GenerateDocResult, type HeadingLevel, INDEX_MARKER_PREFIX, type OptionsRenderContext, type OptionsRenderFunction, type PathConfig, ROOT_FOOTER_MARKER_PREFIX, ROOT_HEADER_MARKER_PREFIX, type RenderContentOptions, type RenderFunction, type RootCommandInfo, type RootDocConfig, SECTION_MARKER_PREFIX, SECTION_TYPES, type SectionRenderFunction, type SectionType, type SimpleRenderContext, type SimpleRenderFunction, type SubCommandInfo, type SubcommandsRenderContext, type SubcommandsRenderFunction, type SubcommandsRenderOptions, UPDATE_GOLDEN_ENV, assertDocMatch, buildCommandInfo, collectAllCommands, compareWithExisting, createCommandRenderer, defaultRenderers, executeExamples, formatDiff, generateDoc, globalOptionsEndMarker, globalOptionsStartMarker, indexEndMarker, indexStartMarker, initDocFile, renderArgsTable, renderArgumentsList, renderArgumentsListFromArray, renderArgumentsTable, renderArgumentsTableFromArray, renderCommandIndex, renderExamplesDefault, renderOptionsList, renderOptionsListFromArray, renderOptionsTable, renderOptionsTableFromArray, renderSubcommandsTable, renderSubcommandsTableFromArray, renderUsage, resolveLazyCommand, rootFooterEndMarker, rootFooterStartMarker, rootHeaderEndMarker, rootHeaderStartMarker, sectionEndMarker, sectionStartMarker, writeFile };
+export { type ArgsShape, type ArgsTableOptions, type ArgumentsRenderContext, type ArgumentsRenderFunction, type CommandCategory, type CommandIndexOptions, type CommandInfo, DOCTOR_ENV, type DefaultRendererOptions, type DeleteFileFs, type ExampleCommandConfig, type ExampleConfig, type ExampleExecutionResult, type ExamplesRenderContext, type ExamplesRenderFunction, type ExamplesRenderOptions, type FileConfig, type FileMapping, type FormatterFunction, GLOBAL_OPTIONS_MARKER_PREFIX, type GenerateDocConfig, type GenerateDocResult, type HeadingLevel, INDEX_MARKER_PREFIX, type OptionsRenderContext, type OptionsRenderFunction, type PathConfig, ROOT_FOOTER_MARKER_PREFIX, ROOT_HEADER_MARKER_PREFIX, type RenderContentOptions, type RenderFunction, type RootCommandInfo, type RootDocConfig, SECTION_MARKER_PREFIX, SECTION_TYPES, type SectionRenderFunction, type SectionType, type SimpleRenderContext, type SimpleRenderFunction, type SubCommandInfo, type SubcommandsRenderContext, type SubcommandsRenderFunction, type SubcommandsRenderOptions, UPDATE_GOLDEN_ENV, assertDocMatch, buildCommandInfo, collectAllCommands, compareWithExisting, createCommandRenderer, defaultRenderers, executeExamples, formatDiff, generateDoc, globalOptionsEndMarker, globalOptionsStartMarker, indexEndMarker, indexStartMarker, initDocFile, renderArgsTable, renderArgumentsList, renderArgumentsListFromArray, renderArgumentsTable, renderArgumentsTableFromArray, renderCommandIndex, renderExamplesDefault, renderOptionsList, renderOptionsListFromArray, renderOptionsTable, renderOptionsTableFromArray, renderSubcommandsTable, renderSubcommandsTableFromArray, renderUsage, resolveLazyCommand, rootFooterEndMarker, rootFooterStartMarker, rootHeaderEndMarker, rootHeaderStartMarker, sectionEndMarker, sectionStartMarker, writeFile };
 //# sourceMappingURL=index.d.ts.map

package/dist/docs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/executor/subcommand-router.ts","../../src/docs/render-args.ts","../../src/docs/types.ts","../../src/docs/default-renderers.ts","../../src/docs/doc-comparator.ts","../../src/docs/doc-generator.ts","../../src/docs/example-executor.ts","../../src/docs/golden-test.ts","../../src/docs/render-index.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/executor/subcommand-router.ts","../../src/docs/render-args.ts","../../src/docs/types.ts","../../src/docs/default-renderers.ts","../../src/docs/doc-comparator.ts","../../src/docs/doc-generator.ts","../../src/docs/example-executor.ts","../../src/docs/golden-test.ts","../../src/docs/render-index.ts"],"mappings":"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"}

package/dist/docs/index.js

@@ -1,5 +1,5 @@
-import { a as getExtractedFields, i as extractFields } from "../lazy-D6nL_iKJ.js";
-import { i as createLogCollector, n as resolveLazyCommand } from "../subcommand-router-Bu3YTw_f.js";
+import { a as getExtractedFields, i as extractFields } from "../lazy-xrzxwnru.js";
+import { i as createLogCollector, n as resolveLazyCommand } from "../subcommand-router-BhYVuS83.js";
 import { z } from "zod";
 import { isDeepStrictEqual } from "node:util";
 import * as fs from "node:fs";
@@ -11,6 +11,12 @@ import * as path from "node:path";
 */
 const UPDATE_GOLDEN_ENV = "POLITTY_DOCS_UPDATE";
 /**
+* Environment variable name for doctor mode.
+* When enabled alone, detects and reports missing section markers (read-only).
+* When combined with POLITTY_DOCS_UPDATE=true, auto-inserts missing markers.
+*/
+const DOCTOR_ENV = "POLITTY_DOCS_DOCTOR";
+/**
 * All section types in rendering order
 */
 const SECTION_TYPES = [
@@ -819,7 +825,7 @@ async function executeSingleExample(example, rootCommand, commandPath) {
 	collector.start();
 	let success = true;
 	try {
-		const { runCommand } = await import("../runner-JZRo4pYu.js").then((n) => n.r);
+		const { runCommand } = await import("../runner-CnG-Ncz0.js").then((n) => n.r);
 		const result = await runCommand(rootCommand, argv);
 		success = result.success;
 		if (!result.success && result.error) console.error(result.error.message);
@@ -1112,11 +1118,8 @@ async function applyFormatter(content, formatter) {
 	if (!content.endsWith("\n") && formatted.endsWith("\n")) return formatted.slice(0, -1);
 	return formatted;
 }
-/**
-* Check if update mode is enabled via environment variable
-*/
-function isUpdateMode() {
-	const value = process.env[UPDATE_GOLDEN_ENV];
+function isTruthyEnv(envKey) {
+	const value = process.env[envKey];
 	return value === "true" || value === "1";
 }
 /**
@@ -1352,6 +1355,54 @@ function replaceSectionMarker(content, type, scope, newContent) {
 	return replaceMarkerSection(content, sectionStartMarker(type, scope), sectionEndMarker(type, scope), newContent);
 }
 /**
+* Insert a new section marker into existing content at the correct position
+* relative to other section markers for the same command, based on SECTION_TYPES order.
+* Preserves any existing content between adjacent markers by wrapping it with the new markers
+* instead of replacing it with generated content.
+* @throws If no adjacent marker is found (unreachable when at least one marker exists for the command)
+*/
+function insertSectionMarkerAtOrder(content, type, scope, generatedSection) {
+	const typeIndex = SECTION_TYPES.indexOf(type);
+	const startMarker = sectionStartMarker(type, scope);
+	const endMarker = sectionEndMarker(type, scope);
+	let prevBoundary = null;
+	for (let i = typeIndex - 1; i >= 0; i--) {
+		const prevType = SECTION_TYPES[i];
+		const prevEnd = sectionEndMarker(prevType, scope);
+		const prevEndIdx = content.indexOf(prevEnd);
+		if (prevEndIdx !== -1) {
+			prevBoundary = prevEndIdx + prevEnd.length;
+			break;
+		}
+	}
+	let nextBoundary = null;
+	for (let i = typeIndex + 1; i < SECTION_TYPES.length; i++) {
+		const nextType = SECTION_TYPES[i];
+		const nextStart = sectionStartMarker(nextType, scope);
+		const nextStartIdx = content.indexOf(nextStart);
+		if (nextStartIdx !== -1) {
+			nextBoundary = nextStartIdx;
+			break;
+		}
+	}
+	if (prevBoundary != null && nextBoundary != null) {
+		const wrapped = startMarker + content.slice(prevBoundary, nextBoundary).replace(/^\n+/, "\n").replace(/\n+$/, "\n") + endMarker;
+		return content.slice(0, prevBoundary) + "\n\n" + wrapped + "\n\n" + content.slice(nextBoundary);
+	}
+	if (prevBoundary != null) {
+		let afterPos = prevBoundary;
+		while (afterPos < content.length && content[afterPos] === "\n") afterPos++;
+		return content.slice(0, prevBoundary) + "\n\n" + generatedSection + (afterPos < content.length ? "\n\n" : "\n") + content.slice(afterPos);
+	}
+	if (nextBoundary != null) {
+		let beforePos = nextBoundary;
+		while (beforePos > 0 && content[beforePos - 1] === "\n") beforePos--;
+		const prefix = beforePos === 0 ? "" : "\n\n";
+		return content.slice(0, beforePos) + prefix + generatedSection + "\n\n" + content.slice(nextBoundary);
+	}
+	throw new Error(`No insertion point found for section "${type}" (scope="${scope}"). This should be unreachable when at least one marker exists for the command.`);
+}
+/**
 * Collect all section types that have markers for a given command path.
 */
 function collectSectionMarkers(content, commandPath) {
@@ -1507,9 +1558,10 @@ function deriveIndexFromFiles(files, rootDocPath, allCommands, ignores) {
 		const docPath = "./" + path.relative(path.dirname(rootDocPath), filePath).replace(/\\/g, "/");
 		const firstCmdPath = commandPaths[0];
 		const cmdInfo = firstCmdPath !== void 0 ? allCommands.get(firstCmdPath) : void 0;
+		const fileConfig = Array.isArray(fileConfigRaw) ? void 0 : fileConfigRaw;
 		categories.push({
-			title: cmdInfo?.name ?? path.basename(filePath, path.extname(filePath)),
-			description: cmdInfo?.description ?? "",
+			title: fileConfig?.title ?? cmdInfo?.name ?? path.basename(filePath, path.extname(filePath)),
+			description: fileConfig?.description ?? cmdInfo?.description ?? "",
 			commands: topLevelCommands,
 			docPath
 		});
@@ -1897,7 +1949,9 @@ async function generateDoc(config) {
 			};
 		}
 	}
-	const updateMode = isUpdateMode();
+	const updateMode = isTruthyEnv(UPDATE_GOLDEN_ENV);
+	const doctorMode = isTruthyEnv(DOCTOR_ENV);
+	let hasDoctorIssues = false;
 	if (rootDoc && !usingPathConfig) {
 		const normalizedRootDocPath = normalizeDocPathForComparison(rootDoc.path);
 		if (Object.keys(files).some((filePath) => normalizeDocPathForComparison(filePath) === normalizedRootDocPath)) throw new Error(`rootDoc.path "${rootDoc.path}" must not also appear as a key in files.`);
@@ -2003,6 +2057,25 @@ async function generateDoc(config) {
 						diffs.push(formatDiff(existingSection, generatedSectionPart));
 					}
 				}
+				if (doctorMode) {
+					const generatedMarkers = collectSectionMarkers(generatedSection, targetCommand);
+					const existingMarkerSet = new Set(existingMarkers);
+					for (const sectionType of generatedMarkers) {
+						if (existingMarkerSet.has(sectionType)) continue;
+						const generatedSectionPart = extractSectionMarker(generatedSection, sectionType, targetCommand);
+						if (!generatedSectionPart) continue;
+						if (updateMode) {
+							existingContent = insertSectionMarkerAtOrder(existingContent, sectionType, targetCommand, generatedSectionPart);
+							writeFile(filePath, existingContent);
+							if (fileStatus !== "created") fileStatus = "updated";
+						} else {
+							hasError = true;
+							hasDoctorIssues = true;
+							fileStatus = "diff";
+							diffs.push(`[doctor] Missing section marker "${sectionType}" for command "${formatCommandPath(targetCommand)}". Run with ${DOCTOR_ENV}=true ${UPDATE_GOLDEN_ENV}=true to insert.\n${generatedSectionPart}`);
+						}
+					}
+				}
 			}
 			if (existingContent) {
 				const existingMarkerPaths = collectSectionMarkerPaths(existingContent);
@@ -2115,10 +2188,11 @@ async function generateDoc(config) {
 			diff: rootDocDiffs.length > 0 ? rootDocDiffs.join("\n\n") : void 0
 		});
 	}
+	const errorHint = hasDoctorIssues ? `Run with ${DOCTOR_ENV}=true ${UPDATE_GOLDEN_ENV}=true to fix missing markers.` : `Run with ${UPDATE_GOLDEN_ENV}=true to update.`;
 	return {
 		success: !hasError,
 		files: results,
-		error: hasError ? `Documentation is out of date. Run with ${UPDATE_GOLDEN_ENV}=true to update.` : void 0
+		error: hasError ? `Documentation is out of date. ${errorHint}` : void 0
 	};
 }
 /**
@@ -2133,7 +2207,7 @@ async function assertDocMatch(config) {
 			if (f.diff) msg += f.diff;
 			return msg;
 		}).join("\n\n");
-		throw new Error(`Documentation does not match golden files.\n\n${diffMessages}\n\nRun with ${UPDATE_GOLDEN_ENV}=true to update the documentation.`);
+		throw new Error(`Documentation does not match golden files.\n\n${diffMessages}\n\n` + (result.error ?? `Run with ${"POLITTY_DOCS_UPDATE"}=true to update the documentation.`));
 	}
 }
 /**
@@ -2144,11 +2218,11 @@ async function assertDocMatch(config) {
 * @param fileSystem - Optional fs implementation (useful when fs is mocked)
 */
 function initDocFile(config, fileSystem) {
-	if (!isUpdateMode()) return;
+	if (!isTruthyEnv("POLITTY_DOCS_UPDATE")) return;
 	if (typeof config === "string") deleteFile(config, fileSystem);
 	else if (config.files) for (const filePath of Object.keys(config.files)) deleteFile(filePath, fileSystem);
 }
 
 //#endregion
-export { GLOBAL_OPTIONS_MARKER_PREFIX, INDEX_MARKER_PREFIX, ROOT_FOOTER_MARKER_PREFIX, ROOT_HEADER_MARKER_PREFIX, SECTION_MARKER_PREFIX, SECTION_TYPES, UPDATE_GOLDEN_ENV, assertDocMatch, buildCommandInfo, collectAllCommands, compareWithExisting, createCommandRenderer, defaultRenderers, executeExamples, formatDiff, generateDoc, globalOptionsEndMarker, globalOptionsStartMarker, indexEndMarker, indexStartMarker, initDocFile, renderArgsTable, renderArgumentsList, renderArgumentsListFromArray, renderArgumentsTable, renderArgumentsTableFromArray, renderCommandIndex, renderExamplesDefault, renderOptionsList, renderOptionsListFromArray, renderOptionsTable, renderOptionsTableFromArray, renderSubcommandsTable, renderSubcommandsTableFromArray, renderUsage, resolveLazyCommand, rootFooterEndMarker, rootFooterStartMarker, rootHeaderEndMarker, rootHeaderStartMarker, sectionEndMarker, sectionStartMarker, writeFile };
+export { DOCTOR_ENV, GLOBAL_OPTIONS_MARKER_PREFIX, INDEX_MARKER_PREFIX, ROOT_FOOTER_MARKER_PREFIX, ROOT_HEADER_MARKER_PREFIX, SECTION_MARKER_PREFIX, SECTION_TYPES, UPDATE_GOLDEN_ENV, assertDocMatch, buildCommandInfo, collectAllCommands, compareWithExisting, createCommandRenderer, defaultRenderers, executeExamples, formatDiff, generateDoc, globalOptionsEndMarker, globalOptionsStartMarker, indexEndMarker, indexStartMarker, initDocFile, renderArgsTable, renderArgumentsList, renderArgumentsListFromArray, renderArgumentsTable, renderArgumentsTableFromArray, renderCommandIndex, renderExamplesDefault, renderOptionsList, renderOptionsListFromArray, renderOptionsTable, renderOptionsTableFromArray, renderSubcommandsTable, renderSubcommandsTableFromArray, renderUsage, resolveLazyCommand, rootFooterEndMarker, rootFooterStartMarker, rootHeaderEndMarker, rootHeaderStartMarker, sectionEndMarker, sectionStartMarker, writeFile };
 //# sourceMappingURL=index.js.map