mdat 0.6.5 → 0.6.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/cli.js +21 -21
- package/dist/index.js +14 -14
- package/dist/readme/rules/description.d.ts +10 -0
- package/dist/readme/rules/index.d.ts +6 -5
- package/dist/readme/rules/short-description.d.ts +5 -0
- package/dist/readme/rules/toc.d.ts +2 -5
- package/package.json +4 -4
- package/readme.md +129 -127
package/bin/cli.js
CHANGED
|
@@ -1,36 +1,36 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
import{defaultLoaders as vn}from"cosmiconfig";function
|
|
3
|
-
${JSON.stringify(t,void 0,2)}`)}function
|
|
4
|
-
${JSON.stringify(t,void 0,2)}`)}var ee;async function P(){return ee===void 0&&(b.warn("getConfig(): config was undefined"),ee??=await L()),ee}var ve;async function h(){let{packageFile:t}=await P();if(t===void 0)throw new Error("No packageFile found or set in config");if(ve??=await
|
|
5
|
-
`)},order:3}};import{globby as
|
|
2
|
+
import{defaultLoaders as vn}from"cosmiconfig";function Ee(t,e){let n=vn[".json"],o=n(t,e);return yt(o)}function yt(t,e="",n={}){for(let[o,i]of Object.entries(t)){let r=e?`${e}.${o}`:o;typeof i=="object"&&i!==null&&!Array.isArray(i)?yt(i,r,n):i===null?n[r]="null":n[r]=i.toString()}return n}import An from"node:fs";import R from"node:path";import{packageUp as $n}from"package-up";import{isFileSync as wt}from"path-type";import Nn from"untildify";function Mn(t,e){let n=e===0?1:Math.floor(Math.log10(Math.abs(e))+1);return t.toString().padStart(n,"0")}function Ct(t,e,n,o){let i=[];for(let[r,s]of t.entries()){let a=n&&t.length>1?`-${Mn(r+1,t.length+1)}`:"",d=Dn(s,e,n,o,a);i.push(d)}return i}function Dn(t,e,n,o,i=""){let r=bt(t),s=e?bt(e):void 0;if(!wt(r))throw new Error(`Input file not found: "${r}"`);if(s){if(wt(s))throw new Error(`Output path must be a directory, received a file path: "${s}"`);An.mkdirSync(s,{recursive:!0})}let a=n?R.basename(n,R.extname(n)):R.basename(r,R.extname(r)),d=`.${o??(n&&R.extname(n)!==""?R.extname(n):R.extname(t)===""?"":R.extname(t))}`,m=`${a}${i}${d}`,c=s??R.dirname(r);return{input:r,name:m,output:c}}function bt(t){return Nn(t)}async function X(){return $n()}function Q(t){return t==null?[]:Array.isArray(t)?t:[t]}import Pt from"chalk";import{cosmiconfig as Rt}from"cosmiconfig";import _n from"node:fs/promises";import xt from"node:path";import In from"plur";import{readPackage as jn}from"read-pkg";import{deepMergeDefined as Le,log as b,optionsSchema as Fn,rulesSchema as Un}from"remark-mdat";import{z as Te}from"zod";var Ot=Fn.merge(Te.object({assetsPath:Te.string().optional(),packageFile:Te.string().optional()})).describe("Config Extension");async function L(t){let{additionalConfig:e,additionalRules:n,searchFrom:o}=t??{},i={addMetaComment:!1,assetsPath:"./assets",closingPrefix:"/",keywordPrefix:"",metaCommentIdentifier:"+",packageFile:await X(),rules:{mdat:"Powered by the Markdown Autophagic Template system: [mdat](https://github.com/kitschpatrol/mdat)."}},r=Rt("mdat"),s=await r.search(o);if(s){let{config:a,filepath:d}=s;b.info(`Using config from "${d}"`);let m=St(a,Ot);m&&(i=Le(i,m))}if(e!==void 0){let a=Array.isArray(e)?e:[e];for(let d of a){let m;if(typeof d=="string"){let p=await r.load(d);if(p==null)continue;let{config:g,filepath:y}=p;b.info(`Loaded additional config from "${y}"`),m=g}else m=d;if(m===void 0)continue;b.info("Merging configuration object");let c=St(m,Ot);c!==void 0&&(i=Le(i,c))}}if(n!==void 0){let a=Array.isArray(n)?n:[n],d=Rt("mdat",{loaders:{".json":Ee}});for(let m of a){let c;if(typeof m=="string"){let g;if(xt.basename(m).endsWith("package.json")){let _=await _n.readFile(m,"utf8");g={config:Ee(m,_),filepath:m}}else g=await d.load(m);if(g==null)continue;let{config:y,filepath:w}=g;b.info(`Loaded additional config from "${w}"`),c=y}else c=m;if(c===void 0)continue;b.info("Merging rules into configuration object");let p=Vn(c,Un);p!==void 0&&(i=Le(i,p))}}if(i.rules){let a=Object.keys(i.rules).sort().map(d=>`"${Pt.bold.green(d)}"`);b.info(`Loaded ${Pt.bold(a.length)} mdat comment expansion ${In("rule",a.length)}:`);for(let d of a)b.info(` ${d}`)}else b.error("No rules loaded from additional configurations or rules, using default.");return ee=i,i}function Vn(t,e){if(e.safeParse(t).success)return{rules:t};b.error(`Rules object has the wrong shape. Ignoring and using default configuration:
|
|
3
|
+
${JSON.stringify(t,void 0,2)}`)}function St(t,e){if(e.safeParse(t).success)return t;b.error(`Config object has the wrong shape. Ignoring and using default configuration:
|
|
4
|
+
${JSON.stringify(t,void 0,2)}`)}var ee;async function P(){return ee===void 0&&(b.warn("getConfig(): config was undefined"),ee??=await L()),ee}var ve;async function h(){let{packageFile:t}=await P();if(t===void 0)throw new Error("No packageFile found or set in config");if(ve??=await jn({cwd:xt.dirname(t)}),ve===void 0)throw new Error("No package.json found");return ve}import{remark as Ae}from"remark";import $e from"remark-gfm";import{mdatCheck as Bn,mdatClean as kt,mdatExpand as Jn,mdatSplit as Et}from"remark-mdat";import{read as Hn}from"to-vfile";import{VFile as Ri}from"vfile";async function S(t,e,n,o,i,r,s){let a=await e({additionalConfig:r,additionalRules:s});r=a;let d=Q(t),m=Ct(d,i,o,"md"),c=[],p=n(a);for(let{input:g,name:y,output:w}of m){let _=await Hn(g),Z=await p.process(_);Z.dirname=w,Z.basename=y,c.push(Z)}return c}function te(t){return Ae().use({settings:{bullet:"-",emphasis:"_"}}).use($e).use(()=>async function(n,o){Et(n,o),kt(n,o,t),await Jn(n,o,t)})}function ne(t){return Ae().use({settings:{bullet:"-",emphasis:"_"}}).use($e).use(()=>function(n,o){Et(n,o),kt(n,o,t)})}function oe(t){return Ae().use({settings:{bullet:"-",emphasis:"_"}}).use($e).use(()=>async function(n,o){await Bn(n,o,{...t,paranoid:!1})})}async function Lt(t,e,n,o,i){return S(t,L,te,e,n,o,i)}async function Tt(t,e,n,o,i){return S(t,L,oe,e,n,o,i)}async function vt(t,e,n,o,i){return S(t,L,ne,e,n,o,i)}import{z as T}from"zod";var ie={badges:{async content(t){var s;let e=T.object({custom:T.record(T.object({image:T.string(),link:T.string()})).optional(),npm:T.array(T.string()).optional()}).optional().parse(t),n=await h(),{name:o}=n,i=[];if(!n.private&&((s=n.publishConfig)==null?void 0:s.access)==="public"&&i.push(`[](https://npmjs.com/package/${o})`),(e==null?void 0:e.npm)!==void 0)for(let a of e.npm)i.push(`[](https://npmjs.com/package/${a})`);let{license:r}=n;if(r!==void 0&&i.push(`[](https://opensource.org/licenses/${r})`),(e==null?void 0:e.custom)!==void 0)for(let[a,{image:d,link:m}]of Object.entries(e.custom))i.push(`[](${m})`);return i.join(`
|
|
5
|
+
`)},order:3}};import{globby as qn}from"globby";import re from"node:path";import{isFile as Gn}from"path-type";import{readPackage as Kn}from"read-pkg";import{z as Ne}from"zod";var se={banner:{async content(t){let e=Ne.object({alt:Ne.string().optional(),src:Ne.string().optional()}).optional().parse(t),{assetsPath:n,packageFile:o}=await P();if(o===void 0)throw new Error("No package.json found");let i=(e==null?void 0:e.src)??await Wn(n);if(i===void 0)throw new Error("Banner image not found at any typical location, consider adding something at ./assets/banner.webp");if(!At(i)&&!await Gn(i))throw new Error(`Banner image not found at "${i}"`);let r=(e==null?void 0:e.alt)??`${(await Kn({cwd:re.dirname(o)})).name} banner`;if(r===void 0||r==="undefined banner")throw new Error("Banner image alt text not available");return``},order:2}};async function Wn(t){let{packageFile:e}=await P();if(e===void 0)throw new Error("No package.json found");let n=re.dirname(e),o=t===void 0?[".","assets","media","readme-assets","readme-media","readme","images"]:[t],i=["banner","header","logo","readme","cover","screenshot","screenshots","demo","overview","image","hero"],r=["png","gif","jpg","jpeg","svg","webp"],s=await qn(o.map(a=>re.join(n,a)),{expandDirectories:{extensions:r,files:i}});if(s.length>0)return re.relative(process.cwd(),s[0])}function At(t,e=!0){if(typeof t!="string")throw new TypeError("Expected a string");if(t=t.trim(),t.includes(" "))return!1;try{return new URL(t),!0}catch{return e?At(`https://${t}`,!1):!1}}function $t(t,e=Number.MAX_SAFE_INTEGER){var i;let n=[],o=Yn(t,e);return n.push(Zn(o)),n.push(Xn(t,o)),o.hasMultipleSubcommands&&o.canRecurse&&n.push(Qn(o.fullCommandName)),((i=o.defaultCommand)==null?void 0:i.commandName)!==void 0&&n.push(eo(o)),n.push(to(t,o)),t.positionals&&!o.commandsOnly&&n.push(Me(["Positional Argument","Description","Type","Default"],t.positionals.map(r=>[r.arguments?[r.arguments.map(s=>`\`${s}\``)].join(" "):"",`${r.description??""}${r.required?" _(Required.)_":" _(Optional.)_"}`,r.type?`\`${r.type}\``:"",r.defaultValue?r.defaultValue.includes(" ")?r.defaultValue:`\`${r.defaultValue}\``:""]))),t.commands&&n.push(Me(["Command","Argument","Description"],t.commands.map(r=>{var s;return[`\`${r.commandName??(r.default?"[default]":"")}\``,r.arguments?(s=r.arguments)==null?void 0:s.map(a=>`\`${a}\``).join(" "):"",`${r.description??""}${r.default?" _(Default command.)_":""}`]}))),t.options&&!o.commandsOnly&&n.push(Me(["Option","Alias","Argument","Description","Type","Default"],t.options.map(r=>[r.flags?r.flags.map(s=>`\`${s}\``).join(" "):"",r.aliases?r.aliases.map(s=>`\`${s}\``).join(" "):"",r.arguments?r.arguments.map(s=>`\`${s}\``).join(" "):"",r.description??"",r.type?`\`${r.type}\``:"",r.defaultValue?r.defaultValue.includes(" ")?r.defaultValue:`\`${r.defaultValue}\``:""]))),o.canRecurse&&o.hasMultipleSubcommands&&n.push("_See the sections below for more information on each subcommand._"),n.join(`
|
|
6
6
|
|
|
7
|
-
`)}function
|
|
7
|
+
`)}function Yn(t,e){var m,c;let n=t.subcommandName===void 0,o=t.commands?t.commands.length>1:!1,i=e>1,r=(m=t.commands)==null?void 0:m.find(p=>p.default),s=(c=t.commands)==null?void 0:c.find(p=>p.commandName===void 0),a=`${t.commandName}${t.subcommandName?` ${t.subcommandName}`:""}`,d=i&&o&&(r==null?void 0:r.commandName)!==void 0;return{canRecurse:i,commandsOnly:d,defaultCommand:r,fullCommandName:a,hasMultipleSubcommands:o,isTopLevel:n,topLevelCommand:s}}function Zn(t){return`#### ${t.isTopLevel?"Command":"Subcommand"}: \`${t.fullCommandName}\``}function Xn(t,e){var n,o;return e.isTopLevel&&((n=e.topLevelCommand)!=null&&n.description)?(t.commands=(o=t.commands)==null?void 0:o.filter(i=>i!==e.topLevelCommand),e.topLevelCommand.description):t.description??""}function Qn(t){return`This section lists top-level commands for \`${t}\`.`}function eo(t){var e,n;return`If no command is provided, \`${(e=t.defaultCommand)==null?void 0:e.parentCommandName} ${(n=t.defaultCommand)==null?void 0:n.commandName}\` is run by default.`}function to(t,e){var o;let n=(o=e.topLevelCommand)!=null&&o.arguments?` ${e.topLevelCommand.arguments.join(" ")}`:`${t.arguments?` ${t.arguments.join(" ")}`:""}`;return`Usage:
|
|
8
8
|
|
|
9
9
|
\`\`\`txt
|
|
10
10
|
${e.fullCommandName}${n}
|
|
11
|
-
\`\`\``}function
|
|
11
|
+
\`\`\``}function Me(t,e){let n=no(e);t=t.filter((i,r)=>!n.includes(r)),e=e.map(i=>i.filter((r,s)=>!n.includes(s)));let o="";o+=`| ${t.join(" | ")} |
|
|
12
12
|
`,o+=`| ${t.map(()=>"---").join(" | ")} |
|
|
13
13
|
`;for(let i of e)o+=`| ${i.join(" | ")} |
|
|
14
|
-
`;return o}function
|
|
14
|
+
`;return o}function no(t){var o;let e=[],n=((o=t[0])==null?void 0:o.length)||0;for(let i=0;i<n;i++){let r=!0;for(let s of t)if(s[i]!==""){r=!1;break}r&&e.push(i)}return e}import{CstParser as oo,Lexer as O,createToken as f}from"chevrotain";var me=f({name:"flag",pattern:/--[\w-_]+/}),Ie=f({longer_alt:me,name:"alias",pattern:/-[A-Za-z]/}),Nt=f({group:O.SKIPPED,name:"comma",pattern:/,/}),Mt=f({group:O.SKIPPED,name:"dollar",pattern:/\$/}),ae=f({group:O.SKIPPED,name:"whiteSpace",pattern:/ /}),Dt=f({group:O.SKIPPED,name:"newLine",pattern:/\n/}),je=f({name:"word",pattern:/\S+/}),H=f({name:"argument",pattern:/(<\S+>|\[.+])/}),Fe=f({name:"programDescription",pattern:/\w.+(?=\n\n {2}Usage)/}),_t=f({group:O.SKIPPED,name:"startUsage",pattern:/ {2}Usage\n/,push_mode:"USAGE_MODE"}),It=f({group:O.SKIPPED,name:"endUsage",pattern:/\n/,pop_mode:!0}),Ue=f({name:"startOptions",pattern:/ {2}Options\n/,push_mode:"OPTIONS_MODE"}),Ve=f({name:"startRow",pattern:/ {4}/,push_mode:"ROW_MODE"}),Be=f({name:"rowDescription",pattern:/\w.+/}),jt=f({group:O.SKIPPED,name:"endRow",pattern:/\n/,pop_mode:!0}),Ft=f({group:O.SKIPPED,name:"endOptions",pattern:/\n/,pop_mode:!0}),io=new O({defaultMode:"DEFAULT_MODE",modes:{DEFAULT_MODE:[_t,Ue,Fe,Dt,ae],OPTIONS_MODE:[Ft,Ve],ROW_MODE:[jt,Ie,me,Nt,H,Be,ae],USAGE_MODE:[It,Mt,H,je,ae]}}),ro=[me,Ie,Nt,Mt,ae,Dt,je,H,Fe,_t,It,Ue,Ve,Be,jt,Ft],De=class extends oo{programHelp=this.RULE("programHelp",()=>{this.CONSUME(Fe,{LABEL:"description"}),this.AT_LEAST_ONE(()=>{this.CONSUME(je,{LABEL:"commandName"})}),this.MANY(()=>{this.CONSUME(H)}),this.OPTION(()=>{this.SUBRULE(this.optionsSection)})});optionsSection=this.RULE("optionsSection",()=>{this.CONSUME(Ue),this.MANY(()=>{this.SUBRULE(this.sectionRow)})});sectionRow=this.RULE("sectionRow",()=>{this.CONSUME(Ve),this.MANY(()=>{this.OR([{ALT:()=>this.CONSUME(H)},{ALT:()=>this.CONSUME(Ie)},{ALT:()=>this.CONSUME(me)},{ALT:()=>this.CONSUME(Be,{LABEL:"description"})}])})});constructor(){super(ro),this.performSelfAnalysis()}},J=new De,_e=class extends J.getBaseCstVisitorConstructor(){constructor(){super(),this.validateVisitor()}programHelp(e){let{command:n,subcommand:o}=de(this.getString(e.commandName));return{arguments:this.getArray(e.argument),commandName:n,description:this.getString(e.description),options:e.optionsSection?this.visit(e.optionsSection):void 0,subcommandName:o}}optionsSection(e){return e.sectionRow.map(n=>this.visit(n))}sectionRow(e){return{aliases:this.getArray(e.alias),arguments:this.getArray(e.argument),description:this.getString(e.description,!0),flags:this.getArray(e.flag)}}getString(e,n=!1){if(e!==void 0)return e.map(o=>n?this.clean(o.image):o.image).join(" ")}getArray(e){if(e!==void 0)return e.map(n=>n.image)}clean(e){return e.replaceAll(/^[\s[]*(default:)?\s*|[\s\]]*$/g,"")}},so=new _e;function Ut(t){let e=io.tokenize(t);if(e.errors.length>0)throw new Error(`Errors lexing CLI command: ${JSON.stringify(e.errors,void 0,2)}`);J.input=e.tokens;let n=J.programHelp();if(J.errors.length>0)throw new Error(`Errors parsing CLI command help text: ${JSON.stringify(J.errors,void 0,2)}`);let o;try{o=so.visit(n)}catch(i){if(i instanceof Error)throw new TypeError(`Errors visiting CLI command help text: ${String(i)}`)}if(o===void 0)throw new Error("Could not parse help string");return o}import{CstParser as ao,Lexer as v,createToken as l}from"chevrotain";var qe=l({name:"flag",pattern:/--[\w-_]+/}),Ge=l({name:"alias",pattern:/-[A-Za-z]/}),Vt=l({group:v.SKIPPED,name:"comma",pattern:/,/}),I=l({name:"word",pattern:/\S+/}),q=l({name:"argument",pattern:/<\S+>|\[\S+]/}),Ke=l({name:"type",pattern:/\[(boolean|string|array)]/}),We=l({name:"defaultInfo",pattern:/\[default]/}),Ye=l({name:"required",pattern:/\[required]/}),Ze=l({name:"defaultInfoDescription",pattern:/\[default:\s.+?]/}),Xe=l({name:"choices",pattern:/\[choices:\s.+?]/}),Je=l({group:v.SKIPPED,name:"whiteSpace",pattern:/\s/}),Bt=l({group:v.SKIPPED,name:"startProgramDescription",pattern:/\n\n/,push_mode:"PROGRAM_DESCRIPTION_MODE"}),Qe=l({name:"programDescription",pattern:/.+/}),Jt=l({group:v.SKIPPED,name:"endProgramDescription",pattern:/\n\n/,pop_mode:!0}),et=l({name:"startOptionsSection",pattern:/Options:?\n/,push_mode:"SECTION_MODE"}),tt=l({name:"startPositionalsSection",pattern:/Positionals:\n/,push_mode:"SECTION_MODE"}),nt=l({name:"startCommandsSection",pattern:/Commands:\n/,push_mode:"SECTION_MODE"}),ot=l({name:"startRow",pattern:/ {2,}/,push_mode:"ROW_MODE"}),it=l({name:"rowDescription",pattern:/ {2}\w.+ {2}/}),rt=l({name:"rowDescriptionTerminal",pattern:/ {2}\w.+/}),Ht=l({group:v.SKIPPED,name:"endRow",pattern:/\n/,pop_mode:!0}),zt=l({group:v.SKIPPED,name:"endSection",pattern:/\n+/,pop_mode:!0}),mo=new v({defaultMode:"DEFAULT_MODE",modes:{DEFAULT_MODE:[et,tt,nt,Bt,q,I,Je],PROGRAM_DESCRIPTION_MODE:[Jt,Qe],ROW_MODE:[Ht,Vt,Ke,it,rt,Ze,We,Ye,Xe,qe,Ge,q,I,Je],SECTION_MODE:[ot,zt]}}),co=[qe,Ge,Vt,I,q,Ke,We,Ye,Ze,Xe,Je,Bt,Qe,Jt,et,tt,nt,ot,it,rt,Ht,zt],He=class extends ao{programHelp=this.RULE("programHelp",()=>{this.AT_LEAST_ONE(()=>{this.CONSUME(I,{LABEL:"commandName"})}),this.MANY1(()=>{this.CONSUME(q)}),this.OPTION(()=>{this.CONSUME(Qe,{LABEL:"description"})}),this.OPTION1(()=>{this.SUBRULE(this.commandsSection)}),this.OPTION2(()=>{this.SUBRULE(this.positionalsSection)}),this.OPTION3(()=>{this.SUBRULE(this.optionsSection)})});positionalsSection=this.RULE("positionalsSection",()=>{this.CONSUME(tt),this.MANY(()=>{this.SUBRULE(this.sectionRow)})});commandsSection=this.RULE("commandsSection",()=>{this.CONSUME(nt),this.MANY1(()=>{this.SUBRULE1(this.sectionRow)})});optionsSection=this.RULE("optionsSection",()=>{this.CONSUME(et),this.MANY2(()=>{this.SUBRULE2(this.sectionRow)})});sectionRow=this.RULE("sectionRow",()=>{this.CONSUME(ot),this.OPTION(()=>{this.CONSUME(I,{LABEL:"parentCommandName"})}),this.MANY(()=>{this.CONSUME1(I,{LABEL:"commandName"})}),this.MANY1(()=>{this.OR([{ALT:()=>this.CONSUME(q)},{ALT:()=>this.CONSUME(Ge)},{ALT:()=>this.CONSUME(qe)},{ALT:()=>this.CONSUME(it,{LABEL:"description"})},{ALT:()=>this.CONSUME(rt,{LABEL:"description"})},{ALT:()=>this.CONSUME(Ke)},{ALT:()=>this.CONSUME(Ye)},{ALT:()=>this.CONSUME(Ze)},{ALT:()=>this.CONSUME(We)},{ALT:()=>this.CONSUME(Xe)}])})});constructor(){super(co),this.performSelfAnalysis()}},z=new He,ze=class extends z.getBaseCstVisitorConstructor(){constructor(){super(),this.validateVisitor()}programHelp(e){let{command:n,subcommand:o}=de(this.getString(e.commandName));return{arguments:this.getArray(e.argument),commandName:n,commands:e.commandsSection?this.visit(e.commandsSection):void 0,description:this.getString(e.description),options:e.optionsSection?this.visit(e.optionsSection):void 0,positionals:e.positionalsSection?this.visit(e.positionalsSection):void 0,subcommandName:o}}positionalsSection(e){return e.sectionRow.map(n=>this.positionalParentCommandToArguments(this.visit(n)))}commandsSection(e){return e.sectionRow.map(n=>this.visit(n))}optionsSection(e){return e.sectionRow.map(n=>this.visit(n))}sectionRow(e){return{aliases:this.getArray(e.alias),arguments:this.getArray(e.argument),choices:this.splitChoices(this.getString(e.choices)),commandName:this.getString(e.commandName),default:e.defaultInfo?!0:void 0,defaultValue:this.getString(e.defaultInfoDescription,!0),description:this.getString(e.description,!0),flags:this.getArray(e.flag),parentCommandName:this.getString(e.parentCommandName),required:e.required?!0:void 0,type:this.getString(e.type,!0)}}positionalParentCommandToArguments(e){let{arguments:n,parentCommandName:o,...i}=e;return o===void 0?e:{arguments:[o,...n??[]],...i}}getString(e,n=!1){if(e!==void 0)return e.map(o=>n?this.clean(o.image):o.image).join(" ")}getArray(e){if(e!==void 0)return e.map(n=>n.image)}clean(e){return e.replaceAll(/^[\s[]*(default:)?\s*|[\s\]]*$/g,"")}splitChoices(e){if(e!==void 0)return this.clean(e.replaceAll(/^\[choices:\s/g,"")).split(", ")}},po=new ze;function qt(t){let e=mo.tokenize(t);if(e.errors.length>0)throw new Error(`Errors lexing CLI command: ${JSON.stringify(e.errors,void 0,2)}`);z.input=e.tokens;let n=z.programHelp();if(z.errors.length>0)throw new Error(`Errors parsing CLI command help text: ${JSON.stringify(z.errors,void 0,2)}`);let o;try{o=po.visit(n)}catch(i){if(i instanceof Error)throw new TypeError(`Errors visiting CLI command help text: ${String(i)}`)}if(o===void 0)throw new Error("Could not parse help string");return o}var Gt={meow:Ut,yargs:qt};function de(t){if(t===void 0)throw new Error('Could not find "commandName" entry in help');let e=t.split(" ");if(e.length===0&&t===void 0)throw new Error('Could not find "commandName" entry in help');if(e.length===1)return{command:e[0],subcommand:void 0};let n=e.at(-1);return{command:e.slice(0,-1).join(" "),subcommand:n}}import{log as st}from"remark-mdat";function Kt(t){for(let[e,n]of Object.entries(Gt)){st.info(`Trying to parse help string with ${e} parser...`);try{return n(t)}catch(o){o instanceof Error&&st.info(`Error in "${e}" parser: ${String(o)}`);continue}}st.error("Could not parse help string with any parser")}import{execaCommand as lo}from"execa";import{log as Wt}from"remark-mdat";async function at(t,e="--help",n){let o=`${t} ${e}`,i=await go(o),r=Kt(i);return r===void 0?(Wt.warn("Falling back to basic cli help text output."),fo(i)):uo(t,e,n??Number.MAX_SAFE_INTEGER,r)}async function uo(t,e,n,o){if(n<=0)return Wt.info("Max CLI command help depth reached, stopping recursion"),"";let i=$t(o,n),r=t.split(" ")[0];if(o.commands)for(let s of o.commands){if(!s.parentCommandName||!s.commandName)continue;let a=await at(`${r} ${s.commandName}`,e,n-1);if(a==="")return i;i+=`
|
|
15
15
|
|
|
16
|
-
${
|
|
16
|
+
${a}`}return i}function fo(t){return`\`\`\`txt
|
|
17
17
|
${t}
|
|
18
|
-
\`\`\``}async function
|
|
18
|
+
\`\`\``}async function go(t){let e;try{let{stderr:n,stdout:o}=await lo(t);e=o,(e===void 0||e==="")&&(e=n)}catch(n){if(n instanceof Error)throw new TypeError(`Error running CLI help command: "${t}"
|
|
19
19
|
${n.message}
|
|
20
20
|
`)}if(e===void 0||e==="")throw new Error(`No result from running CLI help command: "${t}"
|
|
21
|
-
`);return e}import{isExecutable as
|
|
21
|
+
`);return e}import{isExecutable as ho}from"is-executable";import yo from"node:path";import{log as wo}from"remark-mdat";import bo from"which";async function Yt(t){return t??=await Co(),Ro(t)}async function Co(){let t=await h();if(t!=null&&t.bin){let e=typeof t.bin=="string"?t.bin:String(Object.values(t.bin).at(0));if(Po(e))return wo.info(`Inferred <!-- cli-help --> command to run from package.json: ${e}`),e}throw new Error(`Could not infer which command to run for the <!-- cli-help --> rule. Please pass a "cliCommand" option to the expansion comment, e.g. <!-- cli-help {cliCommend: './dist/bin.js'} -->`)}function Po(t){let e=yo.parse(t);return e.root!==""||e.dir!==""}async function Ro(t){let e=await bo(t,{nothrow:!0});if(e===null&&(e=await Oo(t)??void 0),e!==void 0&&await ho(e))return e;throw new Error(`The cli-help rule noticed that "${e}" is not executable.`)}async function Oo(t){var n;let e=await h();return((n=e==null?void 0:e.bin)==null?void 0:n[t])??void 0}import{z as ce}from"zod";var Zt={"cli-help":{async content(t){let e=ce.object({cliCommand:ce.string().optional(),depth:ce.number().optional(),helpFlag:ce.string().optional()}).optional().parse(t),n=await Yt(e==null?void 0:e.cliCommand);return at(n,e==null?void 0:e.helpFlag,e==null?void 0:e.depth)}}};import So from"node:fs/promises";import Xt from"node:path";import{z as mt}from"zod";var Qt={code:{async content(t){let e=mt.object({file:mt.string(),language:mt.string().optional()}).parse(t),n=Xt.extname(e.file)??"",o=await So.readFile(Xt.join(process.cwd(),e.file),"utf8");return`\`\`\`${n}
|
|
22
22
|
${o}
|
|
23
23
|
\`\`\``}}};var pe={contributing:{async content(){var n;let t=await h(),e=(n=t==null?void 0:t.bugs)==null?void 0:n.url;if(e===void 0)throw new Error('Could not find "bugs.url" entry in package.json');return`## Contributing
|
|
24
|
-
[Issues](${e}) and pull requests are welcome.`},order:15}};var le={license:{async content(){let t=await h(),{author:e,license:n}=t;if((e==null?void 0:e.name)===void 0)throw new Error('Could not find "author.name" entry in package.json');if(n===void 0)throw new Error('Could not find "license" entry in package.json');return`## License
|
|
25
|
-
[${n}](license.txt) \xA9 ${e.name}`},order:16}};import{getSoleRule as
|
|
24
|
+
[Issues](${e}) and pull requests are welcome.`},order:15}};var le={description:{async content(){let t=await h();if(t.description===void 0)throw new Error('Could not find "description" entry in package.json');return`**${t.description}**`},order:4}};var ue={license:{async content(){let t=await h(),{author:e,license:n}=t;if((e==null?void 0:e.name)===void 0)throw new Error('Could not find "author.name" entry in package.json');if(n===void 0)throw new Error('Could not find "license" entry in package.json');return`## License
|
|
25
|
+
[${n}](license.txt) \xA9 ${e.name}`},order:16}};import{getSoleRule as en}from"remark-mdat";var tn={footer:{content:[en(pe),en(ue)],order:17}};import{getSoleRule as xo}from"remark-mdat";var fe={"short-description":xo(le)};import{z as ge}from"zod";var he={title:{applicationOrder:2,async content(t){let{postfix:e,prefix:n,titleCase:o}=ge.object({postfix:ge.string().optional().default(""),prefix:ge.string().optional().default(""),titleCase:ge.boolean().optional().default(!1)}).parse(t??{}),{name:i}=await h();return`# ${n}${o?ko(i):i}${e}`},order:1}};function ko(t){return t.split(/[ _-]/).map(e=>e.charAt(0).toUpperCase()+e.slice(1)).join(" ")}import{getSoleRule as ye}from"remark-mdat";var nn={header:{applicationOrder:2,content:[ye(he),ye(se),ye(ie),ye(fe)],order:1}};import{toc as Eo}from"mdast-util-toc";import{remark as Lo}from"remark";import To from"remark-gfm";import{z as x}from"zod";var we={"table-of-contents":{applicationOrder:1,async content(t,e){let n=x.object({depth:x.union([x.literal(1),x.literal(2),x.literal(3),x.literal(4),x.literal(5),x.literal(6)]).optional()}).optional().parse(t),o=Eo(e,{heading:null,maxDepth:(n==null?void 0:n.depth)??3,tight:!0}),i="## Table of contents";if(o.map===void 0)throw new Error("Could not generate table of contents");let r={children:o.map.children,type:"root"},s=Lo().use(To).stringify(r).replaceAll(`
|
|
26
26
|
|
|
27
27
|
`,`
|
|
28
|
-
`);return[i,
|
|
29
|
-
`)},order:6}};import{tldrawToImage as
|
|
28
|
+
`);return[i,s].join(`
|
|
29
|
+
`)},order:6}};import{tldrawToImage as on}from"@kitschpatrol/tldraw-cli";import vo from"node:crypto";import j from"node:fs/promises";import C from"node:path";import{isFile as dt}from"path-type";import{z as ct}from"zod";var mn={tldraw:{async content(t){let{alt:e="tldraw diagram",src:n}=ct.object({alt:ct.string().optional(),src:ct.string()}).parse(t),{assetsPath:o}=await P();if(o===void 0)throw new Error("No assets path found");await j.mkdir(o,{recursive:!0});let i=await dt(n)?await sn(n):void 0;if(i!==void 0){let m=C.basename(n,C.extname(n)),c=C.join(o,`${m}-${i}-light.svg`),p=C.join(o,`${m}-${i}-dark.svg`);if(await dt(c)&&await dt(p))return rn(c,p,e)}let[r]=await on(n,{dark:!1,format:"svg",output:o,transparent:!0});i??=await sn(r);let s=`${an(r)}-${i}-light.svg`;await j.rename(r,s);let[a]=await on(n,{dark:!0,format:"svg",output:o,transparent:!0}),d=`${an(a)}-${i}-dark.svg`;if(await j.rename(a,d),i!==void 0){let m=C.basename(d),c=C.basename(s),p=c.replace(`${i}-light.svg`,""),g=await j.readdir(o);for(let y of g){let w=C.basename(y);w!==m&&w!==c&&w.startsWith(p)&&w.endsWith(".svg")&&await j.rm(C.join(o,w))}}return rn(s,d,e)}}};async function rn(t,e,n){let{packageFile:o}=await P();if(o===void 0)throw new Error("No package file found");let i=C.dirname(o),r=C.relative(i,t);return`<picture>
|
|
30
30
|
<source media="(prefers-color-scheme: dark)" srcset="${C.relative(i,e)}">
|
|
31
31
|
<source media="(prefers-color-scheme: light)" srcset="${r}">
|
|
32
32
|
<img alt="${n}" src="${r}">
|
|
33
|
-
</picture>`}async function
|
|
33
|
+
</picture>`}async function sn(t){let e=await j.readFile(t),n=vo.createHash("sha1");return n.update(e),n.digest("hex").slice(0,8)}function an(t){return t.replace(/\.[^./]+$/,"")}import{getSoleRule as Ao}from"remark-mdat";var dn={toc:Ao(we)};var cn={...ie,...se,...Zt,...Qt,...pe,...le,...tn,...nn,...ue,...fe,...we,...mn,...dn,...he};async function be(t){let e={addMetaComment:!0,rules:cn},{additionalConfig:n=[],...o}=t??{},i=Array.isArray(n)?n:[n],r=await L({additionalConfig:[e,...i],...o});if(r.packageFile===void 0)throw new Error("Package file path is required in `mdat readme` config");return r}import{findUp as $o}from"find-up";import{packageDirectory as No}from"pkg-dir";import{log as pn}from"remark-mdat";async function pt(){pn.info("Searching for package directory...");let t=await No()??process.cwd(),e=await $o("readme.md",{stopAt:t,type:"file"});if(e!==void 0)return pn.info(`Found closest readme at "${e}"`),e}async function Ce(){let t=await pt();if(t===void 0)throw new Error("No readme found");return t}async function Pe(t,e,n,o,i){return t??=await Ce(),S(t,be,te,e,n,o,i)}async function ln(t,e,n,o,i){return t??=await Ce(),S(t,be,oe,e,n,o,i)}async function un(t,e,n,o,i){return t??=await Ce(),S(t,be,ne,e,n,o,i)}var fn=`<!-- header -->
|
|
34
34
|
|
|
35
35
|
<!-- table-of-contents -->
|
|
36
36
|
|
|
@@ -75,7 +75,7 @@ _List maintainer(s) for a repository, along with one way of contacting them (e.g
|
|
|
75
75
|
_State anyone or anything that significantly helped with the development of your project. State public contact hyper-links if applicable._
|
|
76
76
|
|
|
77
77
|
<!-- footer -->
|
|
78
|
-
`;var
|
|
78
|
+
`;var gn=`<!-- title -->
|
|
79
79
|
|
|
80
80
|
<!-- banner -->
|
|
81
81
|
|
|
@@ -128,7 +128,7 @@ _State anyone or anything that significantly helped with the development of your
|
|
|
128
128
|
<!-- contributing -->
|
|
129
129
|
|
|
130
130
|
<!-- license -->
|
|
131
|
-
`;var
|
|
131
|
+
`;var hn=`<!-- header -->
|
|
132
132
|
|
|
133
133
|
## Install
|
|
134
134
|
|
|
@@ -144,7 +144,7 @@ Consider using the <!-- code { src: "path/to/example.ts" } --> comment as well.
|
|
|
144
144
|
\`\`\`
|
|
145
145
|
|
|
146
146
|
<!-- footer -->
|
|
147
|
-
`;var
|
|
147
|
+
`;var yn=`<!-- title -->
|
|
148
148
|
|
|
149
149
|
<!-- short-description -->
|
|
150
150
|
|
|
@@ -166,7 +166,7 @@ Consider using the <!-- code { src: "path/to/example.ts" } --> comment as well.
|
|
|
166
166
|
<!-- contributing -->
|
|
167
167
|
|
|
168
168
|
<!-- license -->
|
|
169
|
-
`;var
|
|
169
|
+
`;var wn=`<!-- header -->
|
|
170
170
|
|
|
171
171
|
_Long description goes here._
|
|
172
172
|
|
|
@@ -229,7 +229,7 @@ _List maintainer(s) for a repository, along with one way of contacting them (e.g
|
|
|
229
229
|
_State anyone or anything that significantly helped with the development of your project. State public contact hyper-links if applicable._
|
|
230
230
|
|
|
231
231
|
<!-- footer -->
|
|
232
|
-
`;var
|
|
232
|
+
`;var bn=`<!-- title -->
|
|
233
233
|
|
|
234
234
|
<!-- banner -->
|
|
235
235
|
|
|
@@ -300,4 +300,4 @@ _State anyone or anything that significantly helped with the development of your
|
|
|
300
300
|
<!-- contributing -->
|
|
301
301
|
|
|
302
302
|
<!-- license -->
|
|
303
|
-
`;var $={"Mdat Readme":{content:{compound:un,explicit:fn},description:"The house style. An expansive starting point. Prune to your context and taste.",exampleLink:"https://github.com/kitschpatrol/mdat/blob/main/readme.md"},"Standard Readme Basic":{content:{compound:gn,explicit:hn},description:'Includes only the "required" sections from the Standard Readme specification.',exampleLink:"https://github.com/RichardLitt/standard-readme/blob/main/example-readmes/minimal-readme.md"},"Standard Readme Full":{content:{compound:yn,explicit:wn},description:"Includes all sections from the Standard Readme specification.",exampleLink:"https://github.com/RichardLitt/standard-readme/blob/main/example-readmes/maximal-readme.md"}};import{confirm as bn,group as jo,intro as Fo,note as Cn,outro as Uo,select as pt}from"@clack/prompts";import x from"chalk";import Vo from"node:fs/promises";import Pe from"node:path";import{deepMergeDefined as Bo}from"remark-mdat";import{write as Jo}from"to-vfile";async function Pn(){let t=await ct(),e=await X();return{packageDirectory:e===void 0?void 0:Pe.dirname(Pe.resolve(e)),readmePath:t}}async function On(){let{packageDirectory:t,readmePath:e}=await Pn(),n=Pe.resolve(process.cwd());Fo(`Running ${x.bold("mdat readme init")} interactively`);let o=await jo({overwrite:async()=>e===void 0||await bn({message:`Found an existing readme at "${x.blue(e)}". Do you want to overwrite it?`,active:"Overwrite",inactive:"Exit"})?!0:(()=>{throw new Error("`mdat readme init` was cancelled to avoid an overwrite - no changes were made")})(),output:async()=>t!==void 0&&t!==n?pt({initialValue:t,message:"There's a root package directory nearby, do you want to create the readme there instead of the current directory?",options:[{label:`Create in the current package root: "${x.blue(t)}"`,value:t},{label:`Create in current working directory: "${x.blue(n)}"`,value:n}]}):n,template:async()=>pt({message:"Which template would you like to use?",options:zo()}),compound:async()=>pt({message:'Do you want to use "compound comments" where possible, which combine several expansions into a single comment block?',options:[{label:`Yes: Combine things like ${x.green("<!-- title -->")} and ${x.green("<!-- badges -->")} in a single ${x.green("<!-- header -->")} comment.`,value:!0},{label:"No: Use individual `mdat` expansion comments for each section.",value:!1}]}),expand:async()=>t===void 0?!1:bn({initialValue:!0,message:"Do you want to run `mdat readme` now to expand the template with content from your package.json?"})},{onCancel(){throw new Error("`mdat readme init` was cancelled - no changes were made")}}),i=await lt(o);return t===void 0&&Cn("No package.json was found. Once you've created one, you can run `mdat readme` to expand the template with content from your package.json."),Cn(`Readme created: "${x.bold.blue(i)}"`),Uo("Done!"),i}async function lt(t){let{packageDirectory:e}=await Pn(),n=Bo({compound:!0,output:e??process.cwd(),overwrite:!0,expand:e!==void 0,template:Object.keys($)[0]},t??{}),o=Ho(n.template,n.compound),i=Pe.join(n.output,"readme.md");await Vo.writeFile(i,o,"utf8");let[r]=await Ce(i);return await Jo(r),i}function Ho(t,e){let o=$[t].content[e?"compound":"explicit"];if(o===void 0||o==="")throw new Error(`No template found for "${t}"`);return o}function zo(){return Object.entries($).map(([t,e])=>({label:t,hint:e.description,value:t}))}var N={config:{defaultDescription:"Configuration is loaded if found from the usual places, or defaults are used.",description:"Path(s) to files containing mdat configs.",string:!0,type:"array"}},G={meta:{alias:"m",description:"Embed an extra comment at the top of the generated Markdown warning editors that certain sections of the document have been generated dynamically.",type:"boolean"}},K={name:{alias:"n",defaultDescription:"Same name as input file. Overwrites the input file.",description:"Output file name.",type:"string"}},F={output:{alias:"o",defaultDescription:"Same directory as input file.",description:"Output file directory.",type:"string"}},A={prefix:{description:"Require a string prefix before all comments to be considered for expansion. Useful if you have a bunch of non-`mdat` comments in your Markdown file, or if you're willing to trade some verbosity for safety.",type:"string"}},W={print:{description:"Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options.",type:"boolean"}},Y={rules:{alias:"r",description:"Path(s) to files containing `mdat` comment expansion rules.",string:!0,type:"array"}},E={verbose:{describe:"Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection.",type:"boolean"}},Oe=["files",{array:!0,demandOption:!0,describe:"Markdown file(s) with `mdat` placeholder comments to collapse.",type:"string"}];var ut={package:{defaultDescription:"The closest package.json file is used by default.",description:"Path to the package.json file to use to populate the readme.",string:!0}},ft={assets:{defaultDescription:"./assets",description:"Path to find and save readme-related assets.",string:!0}},Rn={interactive:{alias:"i",default:!0,description:"Run the guided interactive `init` process. Set explicitly to `false` to use default values and skip the prompt.",type:"boolean"}},Sn={overwrite:{default:!1,defaultDescription:"`false`, if an existing readme is found, don't touch it.",description:"Replace an existing readme file if one is found.",type:"boolean"}},kn={expand:{alias:"e",default:!0,description:"Automatically run `mdat readme` immediately after creating the readme template.",type:"boolean"}},xn={template:{alias:"t",choices:Object.keys($),default:Object.keys($)[0],description:"Specify a template to use for the new readme.",type:"string"}},En={compound:{alias:"c",default:!0,description:"Use compound comment version of the template to replace several individual comment placeholders where possible. This combines things like `<!-- title -->`, `<!-- badges -->`, etc. in a single `<!-- header -->` comment. It's less clutter when you're editing, but it's also less explicit. The final readme.md output is identical.",type:"boolean"}},Re=["files",{array:!0,demandOption:!1,describe:"Readme file(s) with `mdat` placeholder comments to collapse. If not provided, the closest readme.md file is used.",type:"string"}];import gt from"chalk";import _ from"pretty-ms";import{getMdatReports as qo,log as u,reporterMdat as U}from"remark-mdat";import{write as Se}from"to-vfile";import Go from"yargs";import{hideBin as Ko}from"yargs/helpers";var I=performance.now(),Ln=Go(Ko(process.argv));try{await Ln.scriptName("mdat").usage("$0 [command]","Work with `mdat` placeholder comments in any Markdown file.").command(["$0 <files..> [options]","expand <files..> [options]"],"Expand `mdat` placeholder comments.",t=>t.positional(...Oe).option(N).option(Y).option(F).option(K).option(G).option(A).option(W).option(E),async({config:t,files:e,meta:n,name:o,output:i,prefix:r,print:a,rules:s,verbose:d})=>{u.verbose=d??!1,ke({name:o,output:i,print:a});let m=V(t,{addMetaComment:n,keywordPrefix:r}),c=await Et(e,o,i,m,s);for(let p of c)a?process.stdout.write(p.toString()):await Se(p);U(c),u.info(`Expanded comments in ${_(performance.now()-I)}.`),process.exitCode=B(c)}).command("check <files..> [options]","Validate a markdown file with `mdat` placeholder comments.",t=>t.positional(...Oe).option(N).option(Y).option(G).option(A).option(E),async({config:t,files:e,meta:n,prefix:o,rules:i,verbose:r})=>{u.verbose=r??!1;let a=V(t,{addMetaComment:n,keywordPrefix:o}),s=await Lt(e,void 0,void 0,a,i);U(s),u.info(`Checked comments in ${_(performance.now()-I)}.`),process.exitCode=B(s)}).command("collapse <files..> [options]","Collapse `mdat` placeholder comments.",t=>t.positional(...Oe).option(N).option(F).option(K).option(A).option(W).option(E),async({config:t,files:e,name:n,output:o,prefix:i,print:r,verbose:a})=>{u.verbose=a??!1,ke({name:n,output:o,print:r});let s=V(t,{keywordPrefix:i}),d=await vt(e,void 0,void 0,s);for(let m of d)r?process.stdout.write(m.toString()):await Se(m);U(d),u.info(`Cleaned comments in ${_(performance.now()-I)}.`),process.exitCode=B(d)}).command("readme [command]","Work with `mdat` comments in your readme.md.",t=>t.command(["$0 [files..] [options]","expand [files..] [options]"],"Expand `mdat` comment placeholders in your readme.md using a collection of helpful built-in expansion rules.",e=>e.positional(...Re).option(N).option(Y).option(F).option(K).option(ut).option(ft).option(A).option(G).option(W).option(E),async({assets:e,config:n,files:o,meta:i,name:r,output:a,package:s,prefix:d,print:m,rules:c,verbose:p})=>{u.verbose=p??!1,ke({name:r,output:a,print:m});let g=V(n,{addMetaComment:i,assetsPath:e,keywordPrefix:d,packageFile:s}),y=await Ce(o,r,a,g,c);for(let M of y)m?process.stdout.write(M.toString()):await Se(M);U(y);let{packageFile:w}=await P();u.info(`Pulled package metadata from: ${gt.bold.blue(w)}`),u.info(`Expanded readme(s) in ${_(performance.now()-I)}.`),process.exitCode=B(y)}).command("check [files..] [options]","Validate `mdat` placeholder comments in your readme.md.",e=>e.positional(...Re).option(N).option(Y).option(ut).option(ft).option(A).option(G).option(E),async({assets:e,config:n,files:o,meta:i,package:r,prefix:a,rules:s,verbose:d})=>{u.verbose=d??!1;let m=V(n,{addMetaComment:i,assetsPath:e,keywordPrefix:a,packageFile:r}),c=await pn(o,void 0,void 0,m,s);U(c);let{packageFile:p}=await P();u.info(`Pulled package metadata from: ${gt.bold.blue(p)}`),u.info(`Checked readme(s) in ${_(performance.now()-I)}.`),process.exitCode=B(c)}).command("collapse [files..] [options]","Collapse `mdat` placeholder comments in your readme.md.",e=>e.positional(...Re).option(F).option(K).option(W).option(N).option(A).option(E),async({config:e,files:n,name:o,output:i,prefix:r,print:a,verbose:s})=>{u.verbose=s??!1,ke({name:o,output:i,print:a});let d=V(e,{keywordPrefix:r}),m=await ln(n,void 0,void 0,d);for(let c of m)a?process.stdout.write(c.toString()):await Se(c);U(m),u.info(`Cleaned readme(s) in ${_(performance.now()-I)}.`),process.exitCode=B(m)}).command("init [options]","Interactively create a new readme.md file with sensible default `mdat` comment placeholders.",e=>e.option(Rn).option(Sn).option(F).option(kn).option(xn).option(En).option(E),async({compound:e,expand:n,interactive:o,output:i,overwrite:r,template:a,verbose:s})=>{if(u.verbose=s??!1,o)await On();else{let d=await lt({compound:e,expand:n,output:i,overwrite:r,template:a});u.info(`Created readme at "${gt.blue(d)}" in ${_(performance.now()-I)}.`)}process.exitCode=0}),()=>{u.error("Root mdat readme command should be unreachable.")}).help().alias("h","help").version().alias("v","version").wrap(process.stdout.isTTY?Math.min(120,Ln.terminalWidth()):0).fail(!1).parse()}catch(t){t instanceof Error&&u.error(t.message),process.exitCode=1}function ke(t){t.print&&t.output&&u.warn("Ignoring --output option because --print is set"),t.print&&t.name&&u.warn("Ignoring --name option because --print is set")}function V(t,e){return[...Q(t),e]}function B(t){return qo(t).reduce((o,i)=>o+i.errors.length,0)>0?1:0}
|
|
303
|
+
`;var A={"MDAT Readme":{content:{compound:fn,explicit:gn},description:"The house style. An expansive starting point. Prune to your context and taste.",exampleLink:"https://github.com/kitschpatrol/mdat/blob/main/readme.md"},"Standard Readme Basic":{content:{compound:hn,explicit:yn},description:'Includes only the "required" sections from the Standard Readme specification.',exampleLink:"https://github.com/RichardLitt/standard-readme/blob/main/example-readmes/minimal-readme.md"},"Standard Readme Full":{content:{compound:wn,explicit:bn},description:"Includes all sections from the Standard Readme specification.",exampleLink:"https://github.com/RichardLitt/standard-readme/blob/main/example-readmes/maximal-readme.md"}};import{confirm as Cn,group as Uo,intro as Vo,note as Pn,outro as Bo,select as lt}from"@clack/prompts";import k from"chalk";import Jo from"node:fs/promises";import Re from"node:path";import{deepMergeDefined as Ho}from"remark-mdat";import{write as zo}from"to-vfile";async function Rn(){let t=await pt(),e=await X();return{packageDirectory:e===void 0?void 0:Re.dirname(Re.resolve(e)),readmePath:t}}async function On(){let{packageDirectory:t,readmePath:e}=await Rn(),n=Re.resolve(process.cwd());Vo(`Running ${k.bold("mdat readme init")} interactively`);let o=await Uo({overwrite:async()=>e===void 0||await Cn({message:`Found an existing readme at "${k.blue(e)}". Do you want to overwrite it?`,active:"Overwrite",inactive:"Exit"})?!0:(()=>{throw new Error("`mdat readme init` was cancelled to avoid an overwrite - no changes were made")})(),output:async()=>t!==void 0&&t!==n?lt({initialValue:t,message:"There's a root package directory nearby, do you want to create the readme there instead of the current directory?",options:[{label:`Create in the current package root: "${k.blue(t)}"`,value:t},{label:`Create in current working directory: "${k.blue(n)}"`,value:n}]}):n,template:async()=>lt({message:"Which template would you like to use?",options:Go()}),compound:async()=>lt({message:'Do you want to use "compound comments" where possible, which combine several expansions into a single comment block?',options:[{label:`Yes: Combine things like ${k.green("<!-- title -->")} and ${k.green("<!-- badges -->")} in a single ${k.green("<!-- header -->")} comment.`,value:!0},{label:"No: Use individual MDAT expansion comments for each section.",value:!1}]}),expand:async()=>t===void 0?!1:Cn({initialValue:!0,message:"Do you want to run `mdat readme` now to expand the template with content from your package.json?"})},{onCancel(){throw new Error("`mdat readme init` was cancelled - no changes were made")}}),i=await ut(o);return t===void 0&&Pn("No package.json was found. Once you've created one, you can run `mdat readme` to expand the template with content from your package.json."),Pn(`Readme created: "${k.bold.blue(i)}"`),Bo("Done!"),i}async function ut(t){let{packageDirectory:e}=await Rn(),n=Ho({compound:!0,output:e??process.cwd(),overwrite:!0,expand:e!==void 0,template:Object.keys(A)[0]},t??{}),o=qo(n.template,n.compound),i=Re.join(n.output,"readme.md");await Jo.writeFile(i,o,"utf8");let[r]=await Pe(i);return await zo(r),i}function qo(t,e){let o=A[t].content[e?"compound":"explicit"];if(o===void 0||o==="")throw new Error(`No template found for "${t}"`);return o}function Go(){return Object.entries(A).map(([t,e])=>({label:t,hint:e.description,value:t}))}var $={config:{defaultDescription:"Configuration is loaded if found from the usual places, or defaults are used.",description:"Path(s) to files containing MDAT configuration.",string:!0,type:"array"}},G={meta:{alias:"m",description:"Embed an extra comment at the top of the generated Markdown warning editors that certain sections of the document have been generated dynamically.",type:"boolean"}},K={name:{alias:"n",defaultDescription:"Same name as input file. Overwrites the input file.",description:"Output file name.",type:"string"}},F={output:{alias:"o",defaultDescription:"Same directory as input file.",description:"Output file directory.",type:"string"}},N={prefix:{description:"Require a string prefix before all comments to be considered for expansion. Useful if you have a bunch of non-MDAT comments in your Markdown file, or if you're willing to trade some verbosity for safety.",type:"string"}},W={print:{description:"Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options.",type:"boolean"}},Y={rules:{alias:"r",description:"Path(s) to files containing MDAT comment expansion rules.",string:!0,type:"array"}},E={verbose:{describe:"Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection.",type:"boolean"}},Oe=["files",{array:!0,demandOption:!0,describe:"Markdown file(s) with MDAT placeholder comments.",type:"string"}];var ft={package:{defaultDescription:"The closest package.json file is used by default.",description:"Path to the package.json file to use to populate the readme.",string:!0}},gt={assets:{defaultDescription:"./assets",description:"Path to find and save readme-related assets.",string:!0}},Sn={interactive:{alias:"i",default:!0,description:"Run the guided interactive `init` process. Set explicitly to `false` to use default values and skip the prompt.",type:"boolean"}},xn={overwrite:{default:!1,defaultDescription:"`false`, if an existing readme is found, don't touch it.",description:"Replace an existing readme file if one is found.",type:"boolean"}},kn={expand:{alias:"e",default:!0,description:"Automatically run `mdat readme` immediately after creating the readme template.",type:"boolean"}},En={template:{alias:"t",choices:Object.keys(A),default:Object.keys(A)[0],description:"Specify a template to use for the new readme.",type:"string"}},Ln={compound:{alias:"c",default:!0,description:"Use compound comment version of the template to replace several individual comment placeholders where possible. This combines things like `<!-- title -->`, `<!-- badges -->`, etc. in a single `<!-- header -->` comment. It's less clutter when you're editing, but it's also less explicit. The final readme.md output is identical.",type:"boolean"}},Se=["files",{array:!0,demandOption:!1,describe:"Readme file(s) with MDAT placeholder comments. If not provided, the closest readme.md file is used.",type:"string"}];import ht from"chalk";import M from"pretty-ms";import{getMdatReports as Ko,log as u,reporterMdat as U}from"remark-mdat";import{write as xe}from"to-vfile";import Wo from"yargs";import{hideBin as Yo}from"yargs/helpers";var D=performance.now(),Tn=Wo(Yo(process.argv));try{await Tn.scriptName("mdat").usage("$0 [command]","Work with MDAT placeholder comments in any Markdown file.").command(["$0 <files..> [options]","expand <files..> [options]"],"Expand MDAT placeholder comments.",t=>t.positional(...Oe).option($).option(Y).option(F).option(K).option(G).option(N).option(W).option(E),async({config:t,files:e,meta:n,name:o,output:i,prefix:r,print:s,rules:a,verbose:d})=>{u.verbose=d??!1,ke({name:o,output:i,print:s});let m=V(t,{addMetaComment:n,keywordPrefix:r}),c=await Lt(e,o,i,m,a);for(let p of c)s?process.stdout.write(p.toString()):await xe(p);U(c),u.info(`Expanded comments in ${M(performance.now()-D)}.`),process.exitCode=B(c)}).command("check <files..> [options]","Validate a Markdown file containing MDAT placeholder comments.",t=>t.positional(...Oe).option($).option(Y).option(G).option(N).option(E),async({config:t,files:e,meta:n,prefix:o,rules:i,verbose:r})=>{u.verbose=r??!1;let s=V(t,{addMetaComment:n,keywordPrefix:o}),a=await Tt(e,void 0,void 0,s,i);U(a),u.info(`Checked comments in ${M(performance.now()-D)}.`),process.exitCode=B(a)}).command("collapse <files..> [options]","Collapse MDAT placeholder comments.",t=>t.positional(...Oe).option($).option(F).option(K).option(N).option(W).option(E),async({config:t,files:e,name:n,output:o,prefix:i,print:r,verbose:s})=>{u.verbose=s??!1,ke({name:n,output:o,print:r});let a=V(t,{keywordPrefix:i}),d=await vt(e,void 0,void 0,a);for(let m of d)r?process.stdout.write(m.toString()):await xe(m);U(d),u.info(`Cleaned comments in ${M(performance.now()-D)}.`),process.exitCode=B(d)}).command("readme [command]","Work with MDAT comments in your readme.md.",t=>t.command(["$0 [files..] [options]","expand [files..] [options]"],"Expand MDAT comment placeholders in your readme.md using a collection of helpful built-in expansion rules.",e=>e.positional(...Se).option($).option(Y).option(F).option(K).option(ft).option(gt).option(N).option(G).option(W).option(E),async({assets:e,config:n,files:o,meta:i,name:r,output:s,package:a,prefix:d,print:m,rules:c,verbose:p})=>{u.verbose=p??!1,ke({name:r,output:s,print:m});let g=V(n,{addMetaComment:i,assetsPath:e,keywordPrefix:d,packageFile:a}),y=await Pe(o,r,s,g,c);for(let _ of y)m?process.stdout.write(_.toString()):await xe(_);U(y);let{packageFile:w}=await P();u.info(`Pulled package metadata from: ${ht.bold.blue(w)}`),u.info(`Expanded readme(s) in ${M(performance.now()-D)}.`),process.exitCode=B(y)}).command("check [files..] [options]","Validate MDAT placeholder comments in your readme.md.",e=>e.positional(...Se).option($).option(Y).option(ft).option(gt).option(N).option(G).option(E),async({assets:e,config:n,files:o,meta:i,package:r,prefix:s,rules:a,verbose:d})=>{u.verbose=d??!1;let m=V(n,{addMetaComment:i,assetsPath:e,keywordPrefix:s,packageFile:r}),c=await ln(o,void 0,void 0,m,a);U(c);let{packageFile:p}=await P();u.info(`Pulled package metadata from: ${ht.bold.blue(p)}`),u.info(`Checked readme(s) in ${M(performance.now()-D)}.`),process.exitCode=B(c)}).command("collapse [files..] [options]","Collapse MDAT placeholder comments in your readme.md.",e=>e.positional(...Se).option(F).option(K).option(W).option($).option(N).option(E),async({config:e,files:n,name:o,output:i,prefix:r,print:s,verbose:a})=>{u.verbose=a??!1,ke({name:o,output:i,print:s});let d=V(e,{keywordPrefix:r}),m=await un(n,void 0,void 0,d);for(let c of m)s?process.stdout.write(c.toString()):await xe(c);U(m),u.info(`Cleaned readme(s) in ${M(performance.now()-D)}.`),process.exitCode=B(m)}).command("init [options]","Interactively create a new readme.md file with sensible default MDAT comment placeholders.",e=>e.option(Sn).option(xn).option(F).option(kn).option(En).option(Ln).option(E),async({compound:e,expand:n,interactive:o,output:i,overwrite:r,template:s,verbose:a})=>{if(u.verbose=a??!1,o)await On();else{let d=await ut({compound:e,expand:n,output:i,overwrite:r,template:s});u.info(`Created readme at "${ht.blue(d)}" in ${M(performance.now()-D)}.`)}process.exitCode=0}),()=>{u.error("Root MDAT readme command should be unreachable.")}).help().alias("h","help").version().alias("v","version").wrap(process.stdout.isTTY?Math.min(120,Tn.terminalWidth()):0).fail(!1).parse()}catch(t){t instanceof Error&&u.error(t.message),process.exitCode=1}function ke(t){t.print&&t.output&&u.warn("Ignoring --output option because --print is set"),t.print&&t.name&&u.warn("Ignoring --name option because --print is set")}function V(t,e){return[...Q(t),e]}function B(t){return Ko(t).reduce((o,i)=>o+i.errors.length,0)>0?1:0}
|
package/dist/index.js
CHANGED
|
@@ -1,32 +1,32 @@
|
|
|
1
|
-
import{defaultLoaders as
|
|
2
|
-
${JSON.stringify(t,void 0,2)}`)}function
|
|
3
|
-
${JSON.stringify(t,void 0,2)}`)}var V;async function b(){return V===void 0&&(h.warn("getConfig(): config was undefined"),V??=await y()),V}var
|
|
4
|
-
`)},order:3}};import{globby as
|
|
1
|
+
import{defaultLoaders as jt}from"cosmiconfig";function ie(t,e){let n=jt[".json"],o=n(t,e);return Je(o)}function Je(t,e="",n={}){for(let[o,r]of Object.entries(t)){let i=e?`${e}.${o}`:o;typeof r=="object"&&r!==null&&!Array.isArray(r)?Je(r,i,n):r===null?n[i]="null":n[i]=r.toString()}return n}import Dt from"node:fs";import P from"node:path";import{packageUp as Ut}from"package-up";import{isFileSync as Be}from"path-type";import vt from"untildify";function It(t,e){let n=e===0?1:Math.floor(Math.log10(Math.abs(e))+1);return t.toString().padStart(n,"0")}function ze(t,e,n,o){let r=[];for(let[i,s]of t.entries()){let a=n&&t.length>1?`-${It(i+1,t.length+1)}`:"",d=_t(s,e,n,o,a);r.push(d)}return r}function _t(t,e,n,o,r=""){let i=He(t),s=e?He(e):void 0;if(!Be(i))throw new Error(`Input file not found: "${i}"`);if(s){if(Be(s))throw new Error(`Output path must be a directory, received a file path: "${s}"`);Dt.mkdirSync(s,{recursive:!0})}let a=n?P.basename(n,P.extname(n)):P.basename(i,P.extname(i)),d=`.${o??(n&&P.extname(n)!==""?P.extname(n):P.extname(t)===""?"":P.extname(t))}`,m=`${a}${r}${d}`,p=s??P.dirname(i);return{input:i,name:m,output:p}}function He(t){return vt(t)}async function Ke(){return Ut()}function Ge(t){return t==null?[]:Array.isArray(t)?t:[t]}import qe from"chalk";import{cosmiconfig as Ye}from"cosmiconfig";import Vt from"node:fs/promises";import Xe from"node:path";import Jt from"plur";import{readPackage as Bt}from"read-pkg";import{deepMergeDefined as _,log as h,optionsSchema as Ht,rulesSchema as zt}from"remark-mdat";import{z as se}from"zod";var We=Ht.merge(se.object({assetsPath:se.string().optional(),packageFile:se.string().optional()})).describe("Config Extension");async function y(t){let{additionalConfig:e,additionalRules:n,searchFrom:o}=t??{},r={addMetaComment:!1,assetsPath:"./assets",closingPrefix:"/",keywordPrefix:"",metaCommentIdentifier:"+",packageFile:await Ke(),rules:{mdat:"Powered by the Markdown Autophagic Template system: [mdat](https://github.com/kitschpatrol/mdat)."}},i=Ye("mdat"),s=await i.search(o);if(s){let{config:a,filepath:d}=s;h.info(`Using config from "${d}"`);let m=Ze(a,We);m&&(r=_(r,m))}if(e!==void 0){let a=Array.isArray(e)?e:[e];for(let d of a){let m;if(typeof d=="string"){let f=await i.load(d);if(f==null)continue;let{config:g,filepath:L}=f;h.info(`Loaded additional config from "${L}"`),m=g}else m=d;if(m===void 0)continue;h.info("Merging configuration object");let p=Ze(m,We);p!==void 0&&(r=_(r,p))}}if(n!==void 0){let a=Array.isArray(n)?n:[n],d=Ye("mdat",{loaders:{".json":ie}});for(let m of a){let p;if(typeof m=="string"){let g;if(Xe.basename(m).endsWith("package.json")){let re=await Vt.readFile(m,"utf8");g={config:ie(m,re),filepath:m}}else g=await d.load(m);if(g==null)continue;let{config:L,filepath:w}=g;h.info(`Loaded additional config from "${w}"`),p=L}else p=m;if(p===void 0)continue;h.info("Merging rules into configuration object");let f=Kt(p,zt);f!==void 0&&(r=_(r,f))}}if(r.rules){let a=Object.keys(r.rules).sort().map(d=>`"${qe.bold.green(d)}"`);h.info(`Loaded ${qe.bold(a.length)} mdat comment expansion ${Jt("rule",a.length)}:`);for(let d of a)h.info(` ${d}`)}else h.error("No rules loaded from additional configurations or rules, using default.");return V=r,r}function Kt(t,e){if(e.safeParse(t).success)return{rules:t};h.error(`Rules object has the wrong shape. Ignoring and using default configuration:
|
|
2
|
+
${JSON.stringify(t,void 0,2)}`)}function Ze(t,e){if(e.safeParse(t).success)return t;h.error(`Config object has the wrong shape. Ignoring and using default configuration:
|
|
3
|
+
${JSON.stringify(t,void 0,2)}`)}var V;async function b(){return V===void 0&&(h.warn("getConfig(): config was undefined"),V??=await y()),V}var ae;async function l(){let{packageFile:t}=await b();if(t===void 0)throw new Error("No packageFile found or set in config");if(ae??=await Bt({cwd:Xe.dirname(t)}),ae===void 0)throw new Error("No package.json found");return ae}function Gt(t,e){return _(t,e)}import{remark as me}from"remark";import de from"remark-gfm";import{mdatCheck as qt,mdatClean as Qe,mdatExpand as Yt,mdatSplit as et}from"remark-mdat";import{read as Wt}from"to-vfile";import{VFile as Zt}from"vfile";async function E(t,e,n,o,r,i,s){let a=await e({additionalConfig:i,additionalRules:s});i=a;let d=Ge(t),m=ze(d,r,o,"md"),p=[],f=n(a);for(let{input:g,name:L,output:w}of m){let re=await Wt(g),I=await f.process(re);I.dirname=w,I.basename=L,p.push(I)}return p}async function O(t,e,n,o,r){let i=await e({additionalConfig:o,additionalRules:r});return o=i,n(i).process(new Zt(t))}function x(t){return me().use({settings:{bullet:"-",emphasis:"_"}}).use(de).use(()=>async function(n,o){et(n,o),Qe(n,o,t),await Yt(n,o,t)})}function F(t){return me().use({settings:{bullet:"-",emphasis:"_"}}).use(de).use(()=>function(n,o){et(n,o),Qe(n,o,t)})}function $(t){return me().use({settings:{bullet:"-",emphasis:"_"}}).use(de).use(()=>async function(n,o){await qt(n,o,{...t,paranoid:!1})})}async function Xt(t,e,n,o,r){return E(t,y,x,e,n,o,r)}async function Qt(t,e,n){return O(t,y,x,e,n)}async function en(t,e,n,o,r){return E(t,y,$,e,n,o,r)}async function tn(t,e,n){return O(t,y,$,e,n)}async function nn(t,e,n,o,r){return E(t,y,F,e,n,o,r)}async function on(t,e,n){return O(t,y,F,e,n)}import{z as N}from"zod";var J={badges:{async content(t){var s;let e=N.object({custom:N.record(N.object({image:N.string(),link:N.string()})).optional(),npm:N.array(N.string()).optional()}).optional().parse(t),n=await l(),{name:o}=n,r=[];if(!n.private&&((s=n.publishConfig)==null?void 0:s.access)==="public"&&r.push(`[](https://npmjs.com/package/${o})`),(e==null?void 0:e.npm)!==void 0)for(let a of e.npm)r.push(`[](https://npmjs.com/package/${a})`);let{license:i}=n;if(i!==void 0&&r.push(`[](https://opensource.org/licenses/${i})`),(e==null?void 0:e.custom)!==void 0)for(let[a,{image:d,link:m}]of Object.entries(e.custom))r.push(`[](${m})`);return r.join(`
|
|
4
|
+
`)},order:3}};import{globby as rn}from"globby";import B from"node:path";import{isFile as sn}from"path-type";import{readPackage as an}from"read-pkg";import{z as ce}from"zod";var H={banner:{async content(t){let e=ce.object({alt:ce.string().optional(),src:ce.string().optional()}).optional().parse(t),{assetsPath:n,packageFile:o}=await b();if(o===void 0)throw new Error("No package.json found");let r=(e==null?void 0:e.src)??await mn(n);if(r===void 0)throw new Error("Banner image not found at any typical location, consider adding something at ./assets/banner.webp");if(!tt(r)&&!await sn(r))throw new Error(`Banner image not found at "${r}"`);let i=(e==null?void 0:e.alt)??`${(await an({cwd:B.dirname(o)})).name} banner`;if(i===void 0||i==="undefined banner")throw new Error("Banner image alt text not available");return``},order:2}};async function mn(t){let{packageFile:e}=await b();if(e===void 0)throw new Error("No package.json found");let n=B.dirname(e),o=t===void 0?[".","assets","media","readme-assets","readme-media","readme","images"]:[t],r=["banner","header","logo","readme","cover","screenshot","screenshots","demo","overview","image","hero"],i=["png","gif","jpg","jpeg","svg","webp"],s=await rn(o.map(a=>B.join(n,a)),{expandDirectories:{extensions:i,files:r}});if(s.length>0)return B.relative(process.cwd(),s[0])}function tt(t,e=!0){if(typeof t!="string")throw new TypeError("Expected a string");if(t=t.trim(),t.includes(" "))return!1;try{return new URL(t),!0}catch{return e?tt(`https://${t}`,!1):!1}}function nt(t,e=Number.MAX_SAFE_INTEGER){var r;let n=[],o=dn(t,e);return n.push(cn(o)),n.push(pn(t,o)),o.hasMultipleSubcommands&&o.canRecurse&&n.push(fn(o.fullCommandName)),((r=o.defaultCommand)==null?void 0:r.commandName)!==void 0&&n.push(un(o)),n.push(ln(t,o)),t.positionals&&!o.commandsOnly&&n.push(pe(["Positional Argument","Description","Type","Default"],t.positionals.map(i=>[i.arguments?[i.arguments.map(s=>`\`${s}\``)].join(" "):"",`${i.description??""}${i.required?" _(Required.)_":" _(Optional.)_"}`,i.type?`\`${i.type}\``:"",i.defaultValue?i.defaultValue.includes(" ")?i.defaultValue:`\`${i.defaultValue}\``:""]))),t.commands&&n.push(pe(["Command","Argument","Description"],t.commands.map(i=>{var s;return[`\`${i.commandName??(i.default?"[default]":"")}\``,i.arguments?(s=i.arguments)==null?void 0:s.map(a=>`\`${a}\``).join(" "):"",`${i.description??""}${i.default?" _(Default command.)_":""}`]}))),t.options&&!o.commandsOnly&&n.push(pe(["Option","Alias","Argument","Description","Type","Default"],t.options.map(i=>[i.flags?i.flags.map(s=>`\`${s}\``).join(" "):"",i.aliases?i.aliases.map(s=>`\`${s}\``).join(" "):"",i.arguments?i.arguments.map(s=>`\`${s}\``).join(" "):"",i.description??"",i.type?`\`${i.type}\``:"",i.defaultValue?i.defaultValue.includes(" ")?i.defaultValue:`\`${i.defaultValue}\``:""]))),o.canRecurse&&o.hasMultipleSubcommands&&n.push("_See the sections below for more information on each subcommand._"),n.join(`
|
|
5
5
|
|
|
6
|
-
`)}function
|
|
6
|
+
`)}function dn(t,e){var m,p;let n=t.subcommandName===void 0,o=t.commands?t.commands.length>1:!1,r=e>1,i=(m=t.commands)==null?void 0:m.find(f=>f.default),s=(p=t.commands)==null?void 0:p.find(f=>f.commandName===void 0),a=`${t.commandName}${t.subcommandName?` ${t.subcommandName}`:""}`,d=r&&o&&(i==null?void 0:i.commandName)!==void 0;return{canRecurse:r,commandsOnly:d,defaultCommand:i,fullCommandName:a,hasMultipleSubcommands:o,isTopLevel:n,topLevelCommand:s}}function cn(t){return`#### ${t.isTopLevel?"Command":"Subcommand"}: \`${t.fullCommandName}\``}function pn(t,e){var n,o;return e.isTopLevel&&((n=e.topLevelCommand)!=null&&n.description)?(t.commands=(o=t.commands)==null?void 0:o.filter(r=>r!==e.topLevelCommand),e.topLevelCommand.description):t.description??""}function fn(t){return`This section lists top-level commands for \`${t}\`.`}function un(t){var e,n;return`If no command is provided, \`${(e=t.defaultCommand)==null?void 0:e.parentCommandName} ${(n=t.defaultCommand)==null?void 0:n.commandName}\` is run by default.`}function ln(t,e){var o;let n=(o=e.topLevelCommand)!=null&&o.arguments?` ${e.topLevelCommand.arguments.join(" ")}`:`${t.arguments?` ${t.arguments.join(" ")}`:""}`;return`Usage:
|
|
7
7
|
|
|
8
8
|
\`\`\`txt
|
|
9
9
|
${e.fullCommandName}${n}
|
|
10
|
-
\`\`\``}function
|
|
10
|
+
\`\`\``}function pe(t,e){let n=gn(e);t=t.filter((r,i)=>!n.includes(i)),e=e.map(r=>r.filter((i,s)=>!n.includes(s)));let o="";o+=`| ${t.join(" | ")} |
|
|
11
11
|
`,o+=`| ${t.map(()=>"---").join(" | ")} |
|
|
12
12
|
`;for(let r of e)o+=`| ${r.join(" | ")} |
|
|
13
|
-
`;return o}function
|
|
13
|
+
`;return o}function gn(t){var o;let e=[],n=((o=t[0])==null?void 0:o.length)||0;for(let r=0;r<n;r++){let i=!0;for(let s of t)if(s[r]!==""){i=!1;break}i&&e.push(r)}return e}import{CstParser as hn,Lexer as S,createToken as u}from"chevrotain";var K=u({name:"flag",pattern:/--[\w-_]+/}),le=u({longer_alt:K,name:"alias",pattern:/-[A-Za-z]/}),ot=u({group:S.SKIPPED,name:"comma",pattern:/,/}),rt=u({group:S.SKIPPED,name:"dollar",pattern:/\$/}),z=u({group:S.SKIPPED,name:"whiteSpace",pattern:/ /}),it=u({group:S.SKIPPED,name:"newLine",pattern:/\n/}),ge=u({name:"word",pattern:/\S+/}),D=u({name:"argument",pattern:/(<\S+>|\[.+])/}),he=u({name:"programDescription",pattern:/\w.+(?=\n\n {2}Usage)/}),st=u({group:S.SKIPPED,name:"startUsage",pattern:/ {2}Usage\n/,push_mode:"USAGE_MODE"}),at=u({group:S.SKIPPED,name:"endUsage",pattern:/\n/,pop_mode:!0}),ye=u({name:"startOptions",pattern:/ {2}Options\n/,push_mode:"OPTIONS_MODE"}),Ce=u({name:"startRow",pattern:/ {4}/,push_mode:"ROW_MODE"}),we=u({name:"rowDescription",pattern:/\w.+/}),mt=u({group:S.SKIPPED,name:"endRow",pattern:/\n/,pop_mode:!0}),dt=u({group:S.SKIPPED,name:"endOptions",pattern:/\n/,pop_mode:!0}),yn=new S({defaultMode:"DEFAULT_MODE",modes:{DEFAULT_MODE:[st,ye,he,it,z],OPTIONS_MODE:[dt,Ce],ROW_MODE:[mt,le,K,ot,D,we,z],USAGE_MODE:[at,rt,D,ge,z]}}),Cn=[K,le,ot,rt,z,it,ge,D,he,st,at,ye,Ce,we,mt,dt],fe=class extends hn{programHelp=this.RULE("programHelp",()=>{this.CONSUME(he,{LABEL:"description"}),this.AT_LEAST_ONE(()=>{this.CONSUME(ge,{LABEL:"commandName"})}),this.MANY(()=>{this.CONSUME(D)}),this.OPTION(()=>{this.SUBRULE(this.optionsSection)})});optionsSection=this.RULE("optionsSection",()=>{this.CONSUME(ye),this.MANY(()=>{this.SUBRULE(this.sectionRow)})});sectionRow=this.RULE("sectionRow",()=>{this.CONSUME(Ce),this.MANY(()=>{this.OR([{ALT:()=>this.CONSUME(D)},{ALT:()=>this.CONSUME(le)},{ALT:()=>this.CONSUME(K)},{ALT:()=>this.CONSUME(we,{LABEL:"description"})}])})});constructor(){super(Cn),this.performSelfAnalysis()}},j=new fe,ue=class extends j.getBaseCstVisitorConstructor(){constructor(){super(),this.validateVisitor()}programHelp(e){let{command:n,subcommand:o}=G(this.getString(e.commandName));return{arguments:this.getArray(e.argument),commandName:n,description:this.getString(e.description),options:e.optionsSection?this.visit(e.optionsSection):void 0,subcommandName:o}}optionsSection(e){return e.sectionRow.map(n=>this.visit(n))}sectionRow(e){return{aliases:this.getArray(e.alias),arguments:this.getArray(e.argument),description:this.getString(e.description,!0),flags:this.getArray(e.flag)}}getString(e,n=!1){if(e!==void 0)return e.map(o=>n?this.clean(o.image):o.image).join(" ")}getArray(e){if(e!==void 0)return e.map(n=>n.image)}clean(e){return e.replaceAll(/^[\s[]*(default:)?\s*|[\s\]]*$/g,"")}},wn=new ue;function ct(t){let e=yn.tokenize(t);if(e.errors.length>0)throw new Error(`Errors lexing CLI command: ${JSON.stringify(e.errors,void 0,2)}`);j.input=e.tokens;let n=j.programHelp();if(j.errors.length>0)throw new Error(`Errors parsing CLI command help text: ${JSON.stringify(j.errors,void 0,2)}`);let o;try{o=wn.visit(n)}catch(r){if(r instanceof Error)throw new TypeError(`Errors visiting CLI command help text: ${String(r)}`)}if(o===void 0)throw new Error("Could not parse help string");return o}import{CstParser as Pn,Lexer as k,createToken as c}from"chevrotain";var Re=c({name:"flag",pattern:/--[\w-_]+/}),Le=c({name:"alias",pattern:/-[A-Za-z]/}),pt=c({group:k.SKIPPED,name:"comma",pattern:/,/}),A=c({name:"word",pattern:/\S+/}),v=c({name:"argument",pattern:/<\S+>|\[\S+]/}),be=c({name:"type",pattern:/\[(boolean|string|array)]/}),Oe=c({name:"defaultInfo",pattern:/\[default]/}),Ne=c({name:"required",pattern:/\[required]/}),ke=c({name:"defaultInfoDescription",pattern:/\[default:\s.+?]/}),Te=c({name:"choices",pattern:/\[choices:\s.+?]/}),Pe=c({group:k.SKIPPED,name:"whiteSpace",pattern:/\s/}),ft=c({group:k.SKIPPED,name:"startProgramDescription",pattern:/\n\n/,push_mode:"PROGRAM_DESCRIPTION_MODE"}),xe=c({name:"programDescription",pattern:/.+/}),ut=c({group:k.SKIPPED,name:"endProgramDescription",pattern:/\n\n/,pop_mode:!0}),$e=c({name:"startOptionsSection",pattern:/Options:?\n/,push_mode:"SECTION_MODE"}),Ae=c({name:"startPositionalsSection",pattern:/Positionals:\n/,push_mode:"SECTION_MODE"}),Me=c({name:"startCommandsSection",pattern:/Commands:\n/,push_mode:"SECTION_MODE"}),Fe=c({name:"startRow",pattern:/ {2,}/,push_mode:"ROW_MODE"}),je=c({name:"rowDescription",pattern:/ {2}\w.+ {2}/}),De=c({name:"rowDescriptionTerminal",pattern:/ {2}\w.+/}),lt=c({group:k.SKIPPED,name:"endRow",pattern:/\n/,pop_mode:!0}),gt=c({group:k.SKIPPED,name:"endSection",pattern:/\n+/,pop_mode:!0}),Sn=new k({defaultMode:"DEFAULT_MODE",modes:{DEFAULT_MODE:[$e,Ae,Me,ft,v,A,Pe],PROGRAM_DESCRIPTION_MODE:[ut,xe],ROW_MODE:[lt,pt,be,je,De,ke,Oe,Ne,Te,Re,Le,v,A,Pe],SECTION_MODE:[Fe,gt]}}),En=[Re,Le,pt,A,v,be,Oe,Ne,ke,Te,Pe,ft,xe,ut,$e,Ae,Me,Fe,je,De,lt,gt],Se=class extends Pn{programHelp=this.RULE("programHelp",()=>{this.AT_LEAST_ONE(()=>{this.CONSUME(A,{LABEL:"commandName"})}),this.MANY1(()=>{this.CONSUME(v)}),this.OPTION(()=>{this.CONSUME(xe,{LABEL:"description"})}),this.OPTION1(()=>{this.SUBRULE(this.commandsSection)}),this.OPTION2(()=>{this.SUBRULE(this.positionalsSection)}),this.OPTION3(()=>{this.SUBRULE(this.optionsSection)})});positionalsSection=this.RULE("positionalsSection",()=>{this.CONSUME(Ae),this.MANY(()=>{this.SUBRULE(this.sectionRow)})});commandsSection=this.RULE("commandsSection",()=>{this.CONSUME(Me),this.MANY1(()=>{this.SUBRULE1(this.sectionRow)})});optionsSection=this.RULE("optionsSection",()=>{this.CONSUME($e),this.MANY2(()=>{this.SUBRULE2(this.sectionRow)})});sectionRow=this.RULE("sectionRow",()=>{this.CONSUME(Fe),this.OPTION(()=>{this.CONSUME(A,{LABEL:"parentCommandName"})}),this.MANY(()=>{this.CONSUME1(A,{LABEL:"commandName"})}),this.MANY1(()=>{this.OR([{ALT:()=>this.CONSUME(v)},{ALT:()=>this.CONSUME(Le)},{ALT:()=>this.CONSUME(Re)},{ALT:()=>this.CONSUME(je,{LABEL:"description"})},{ALT:()=>this.CONSUME(De,{LABEL:"description"})},{ALT:()=>this.CONSUME(be)},{ALT:()=>this.CONSUME(Ne)},{ALT:()=>this.CONSUME(ke)},{ALT:()=>this.CONSUME(Oe)},{ALT:()=>this.CONSUME(Te)}])})});constructor(){super(En),this.performSelfAnalysis()}},U=new Se,Ee=class extends U.getBaseCstVisitorConstructor(){constructor(){super(),this.validateVisitor()}programHelp(e){let{command:n,subcommand:o}=G(this.getString(e.commandName));return{arguments:this.getArray(e.argument),commandName:n,commands:e.commandsSection?this.visit(e.commandsSection):void 0,description:this.getString(e.description),options:e.optionsSection?this.visit(e.optionsSection):void 0,positionals:e.positionalsSection?this.visit(e.positionalsSection):void 0,subcommandName:o}}positionalsSection(e){return e.sectionRow.map(n=>this.positionalParentCommandToArguments(this.visit(n)))}commandsSection(e){return e.sectionRow.map(n=>this.visit(n))}optionsSection(e){return e.sectionRow.map(n=>this.visit(n))}sectionRow(e){return{aliases:this.getArray(e.alias),arguments:this.getArray(e.argument),choices:this.splitChoices(this.getString(e.choices)),commandName:this.getString(e.commandName),default:e.defaultInfo?!0:void 0,defaultValue:this.getString(e.defaultInfoDescription,!0),description:this.getString(e.description,!0),flags:this.getArray(e.flag),parentCommandName:this.getString(e.parentCommandName),required:e.required?!0:void 0,type:this.getString(e.type,!0)}}positionalParentCommandToArguments(e){let{arguments:n,parentCommandName:o,...r}=e;return o===void 0?e:{arguments:[o,...n??[]],...r}}getString(e,n=!1){if(e!==void 0)return e.map(o=>n?this.clean(o.image):o.image).join(" ")}getArray(e){if(e!==void 0)return e.map(n=>n.image)}clean(e){return e.replaceAll(/^[\s[]*(default:)?\s*|[\s\]]*$/g,"")}splitChoices(e){if(e!==void 0)return this.clean(e.replaceAll(/^\[choices:\s/g,"")).split(", ")}},Rn=new Ee;function ht(t){let e=Sn.tokenize(t);if(e.errors.length>0)throw new Error(`Errors lexing CLI command: ${JSON.stringify(e.errors,void 0,2)}`);U.input=e.tokens;let n=U.programHelp();if(U.errors.length>0)throw new Error(`Errors parsing CLI command help text: ${JSON.stringify(U.errors,void 0,2)}`);let o;try{o=Rn.visit(n)}catch(r){if(r instanceof Error)throw new TypeError(`Errors visiting CLI command help text: ${String(r)}`)}if(o===void 0)throw new Error("Could not parse help string");return o}var yt={meow:ct,yargs:ht};function G(t){if(t===void 0)throw new Error('Could not find "commandName" entry in help');let e=t.split(" ");if(e.length===0&&t===void 0)throw new Error('Could not find "commandName" entry in help');if(e.length===1)return{command:e[0],subcommand:void 0};let n=e.at(-1);return{command:e.slice(0,-1).join(" "),subcommand:n}}import{log as Ue}from"remark-mdat";function Ct(t){for(let[e,n]of Object.entries(yt)){Ue.info(`Trying to parse help string with ${e} parser...`);try{return n(t)}catch(o){o instanceof Error&&Ue.info(`Error in "${e}" parser: ${String(o)}`);continue}}Ue.error("Could not parse help string with any parser")}import{execaCommand as Ln}from"execa";import{log as wt}from"remark-mdat";async function ve(t,e="--help",n){let o=`${t} ${e}`,r=await Nn(o),i=Ct(r);return i===void 0?(wt.warn("Falling back to basic cli help text output."),On(r)):bn(t,e,n??Number.MAX_SAFE_INTEGER,i)}async function bn(t,e,n,o){if(n<=0)return wt.info("Max CLI command help depth reached, stopping recursion"),"";let r=nt(o,n),i=t.split(" ")[0];if(o.commands)for(let s of o.commands){if(!s.parentCommandName||!s.commandName)continue;let a=await ve(`${i} ${s.commandName}`,e,n-1);if(a==="")return r;r+=`
|
|
14
14
|
|
|
15
|
-
${a}`}return r}function
|
|
15
|
+
${a}`}return r}function On(t){return`\`\`\`txt
|
|
16
16
|
${t}
|
|
17
|
-
\`\`\``}async function
|
|
17
|
+
\`\`\``}async function Nn(t){let e;try{let{stderr:n,stdout:o}=await Ln(t);e=o,(e===void 0||e==="")&&(e=n)}catch(n){if(n instanceof Error)throw new TypeError(`Error running CLI help command: "${t}"
|
|
18
18
|
${n.message}
|
|
19
19
|
`)}if(e===void 0||e==="")throw new Error(`No result from running CLI help command: "${t}"
|
|
20
|
-
`);return e}import{isExecutable as kn}from"is-executable";import
|
|
20
|
+
`);return e}import{isExecutable as kn}from"is-executable";import Tn from"node:path";import{log as xn}from"remark-mdat";import $n from"which";async function Pt(t){return t??=await An(),Fn(t)}async function An(){let t=await l();if(t!=null&&t.bin){let e=typeof t.bin=="string"?t.bin:String(Object.values(t.bin).at(0));if(Mn(e))return xn.info(`Inferred <!-- cli-help --> command to run from package.json: ${e}`),e}throw new Error(`Could not infer which command to run for the <!-- cli-help --> rule. Please pass a "cliCommand" option to the expansion comment, e.g. <!-- cli-help {cliCommend: './dist/bin.js'} -->`)}function Mn(t){let e=Tn.parse(t);return e.root!==""||e.dir!==""}async function Fn(t){let e=await $n(t,{nothrow:!0});if(e===null&&(e=await jn(t)??void 0),e!==void 0&&await kn(e))return e;throw new Error(`The cli-help rule noticed that "${e}" is not executable.`)}async function jn(t){var n;let e=await l();return((n=e==null?void 0:e.bin)==null?void 0:n[t])??void 0}import{z as q}from"zod";var St={"cli-help":{async content(t){let e=q.object({cliCommand:q.string().optional(),depth:q.number().optional(),helpFlag:q.string().optional()}).optional().parse(t),n=await Pt(e==null?void 0:e.cliCommand);return ve(n,e==null?void 0:e.helpFlag,e==null?void 0:e.depth)}}};import Dn from"node:fs/promises";import Et from"node:path";import{z as Ie}from"zod";var Rt={code:{async content(t){let e=Ie.object({file:Ie.string(),language:Ie.string().optional()}).parse(t),n=Et.extname(e.file)??"",o=await Dn.readFile(Et.join(process.cwd(),e.file),"utf8");return`\`\`\`${n}
|
|
21
21
|
${o}
|
|
22
22
|
\`\`\``}}};var Y={contributing:{async content(){var n;let t=await l(),e=(n=t==null?void 0:t.bugs)==null?void 0:n.url;if(e===void 0)throw new Error('Could not find "bugs.url" entry in package.json');return`## Contributing
|
|
23
|
-
[Issues](${e}) and pull requests are welcome.`},order:15}};var W={license:{async content(){let t=await l(),{author:e,license:n}=t;if((e==null?void 0:e.name)===void 0)throw new Error('Could not find "author.name" entry in package.json');if(n===void 0)throw new Error('Could not find "license" entry in package.json');return`## License
|
|
24
|
-
[${n}](license.txt) \xA9 ${e.name}`},order:16}};import{getSoleRule as
|
|
23
|
+
[Issues](${e}) and pull requests are welcome.`},order:15}};var W={description:{async content(){let t=await l();if(t.description===void 0)throw new Error('Could not find "description" entry in package.json');return`**${t.description}**`},order:4}};var Z={license:{async content(){let t=await l(),{author:e,license:n}=t;if((e==null?void 0:e.name)===void 0)throw new Error('Could not find "author.name" entry in package.json');if(n===void 0)throw new Error('Could not find "license" entry in package.json');return`## License
|
|
24
|
+
[${n}](license.txt) \xA9 ${e.name}`},order:16}};import{getSoleRule as Lt}from"remark-mdat";var bt={footer:{content:[Lt(Y),Lt(Z)],order:17}};import{getSoleRule as Un}from"remark-mdat";var X={"short-description":Un(W)};import{z as Q}from"zod";var ee={title:{applicationOrder:2,async content(t){let{postfix:e,prefix:n,titleCase:o}=Q.object({postfix:Q.string().optional().default(""),prefix:Q.string().optional().default(""),titleCase:Q.boolean().optional().default(!1)}).parse(t??{}),{name:r}=await l();return`# ${n}${o?vn(r):r}${e}`},order:1}};function vn(t){return t.split(/[ _-]/).map(e=>e.charAt(0).toUpperCase()+e.slice(1)).join(" ")}import{getSoleRule as te}from"remark-mdat";var Ot={header:{applicationOrder:2,content:[te(ee),te(H),te(J),te(X)],order:1}};import{toc as In}from"mdast-util-toc";import{remark as _n}from"remark";import Vn from"remark-gfm";import{z as R}from"zod";var ne={"table-of-contents":{applicationOrder:1,async content(t,e){let n=R.object({depth:R.union([R.literal(1),R.literal(2),R.literal(3),R.literal(4),R.literal(5),R.literal(6)]).optional()}).optional().parse(t),o=In(e,{heading:null,maxDepth:(n==null?void 0:n.depth)??3,tight:!0}),r="## Table of contents";if(o.map===void 0)throw new Error("Could not generate table of contents");let i={children:o.map.children,type:"root"},s=_n().use(Vn).stringify(i).replaceAll(`
|
|
25
25
|
|
|
26
26
|
`,`
|
|
27
27
|
`);return[r,s].join(`
|
|
28
|
-
`)},order:6}};import{tldrawToImage as
|
|
28
|
+
`)},order:6}};import{tldrawToImage as Nt}from"@kitschpatrol/tldraw-cli";import Jn from"node:crypto";import M from"node:fs/promises";import C from"node:path";import{isFile as _e}from"path-type";import{z as Ve}from"zod";var $t={tldraw:{async content(t){let{alt:e="tldraw diagram",src:n}=Ve.object({alt:Ve.string().optional(),src:Ve.string()}).parse(t),{assetsPath:o}=await b();if(o===void 0)throw new Error("No assets path found");await M.mkdir(o,{recursive:!0});let r=await _e(n)?await Tt(n):void 0;if(r!==void 0){let m=C.basename(n,C.extname(n)),p=C.join(o,`${m}-${r}-light.svg`),f=C.join(o,`${m}-${r}-dark.svg`);if(await _e(p)&&await _e(f))return kt(p,f,e)}let[i]=await Nt(n,{dark:!1,format:"svg",output:o,transparent:!0});r??=await Tt(i);let s=`${xt(i)}-${r}-light.svg`;await M.rename(i,s);let[a]=await Nt(n,{dark:!0,format:"svg",output:o,transparent:!0}),d=`${xt(a)}-${r}-dark.svg`;if(await M.rename(a,d),r!==void 0){let m=C.basename(d),p=C.basename(s),f=p.replace(`${r}-light.svg`,""),g=await M.readdir(o);for(let L of g){let w=C.basename(L);w!==m&&w!==p&&w.startsWith(f)&&w.endsWith(".svg")&&await M.rm(C.join(o,w))}}return kt(s,d,e)}}};async function kt(t,e,n){let{packageFile:o}=await b();if(o===void 0)throw new Error("No package file found");let r=C.dirname(o),i=C.relative(r,t);return`<picture>
|
|
29
29
|
<source media="(prefers-color-scheme: dark)" srcset="${C.relative(r,e)}">
|
|
30
30
|
<source media="(prefers-color-scheme: light)" srcset="${i}">
|
|
31
31
|
<img alt="${n}" src="${i}">
|
|
32
|
-
</picture>`}async function
|
|
32
|
+
</picture>`}async function Tt(t){let e=await M.readFile(t),n=Jn.createHash("sha1");return n.update(e),n.digest("hex").slice(0,8)}function xt(t){return t.replace(/\.[^./]+$/,"")}import{getSoleRule as Bn}from"remark-mdat";var At={toc:Bn(ne)};var Mt={...J,...H,...St,...Rt,...Y,...W,...bt,...Ot,...Z,...X,...ne,...$t,...At,...ee};async function T(t){let e={addMetaComment:!0,rules:Mt},{additionalConfig:n=[],...o}=t??{},r=Array.isArray(n)?n:[n],i=await y({additionalConfig:[e,...r],...o});if(i.packageFile===void 0)throw new Error("Package file path is required in `mdat readme` config");return i}import{findUp as Hn}from"find-up";import{packageDirectory as zn}from"pkg-dir";import{log as Ft}from"remark-mdat";async function Kn(){Ft.info("Searching for package directory...");let t=await zn()??process.cwd(),e=await Hn("readme.md",{stopAt:t,type:"file"});if(e!==void 0)return Ft.info(`Found closest readme at "${e}"`),e}async function oe(){let t=await Kn();if(t===void 0)throw new Error("No readme found");return t}async function Gn(t,e,n,o,r){return t??=await oe(),E(t,T,x,e,n,o,r)}async function qn(t,e,n){return O(t,T,x,e,n)}async function Yn(t,e,n,o,r){return t??=await oe(),E(t,T,$,e,n,o,r)}async function Wn(t,e,n){return O(t,T,$,e,n)}async function Zn(t,e,n,o,r){return t??=await oe(),E(t,T,F,e,n,o,r)}export{en as checkFiles,Yn as checkReadmeFiles,Wn as checkReadmeString,tn as checkString,nn as collapseFiles,Zn as collapseReadmeFiles,on as collapseString,Xt as expandFiles,Gn as expandReadmeFiles,qn as expandReadmeString,Qt as expandString,y as loadConfig,T as loadConfigReadme,Gt as mergeConfigs};
|
|
@@ -6,11 +6,8 @@ declare const _default: {
|
|
|
6
6
|
};
|
|
7
7
|
toc: {
|
|
8
8
|
applicationOrder: number;
|
|
9
|
-
content:
|
|
10
|
-
|
|
11
|
-
content(options: import("type-fest").JsonValue, tree: import("mdast").Root): Promise<string>;
|
|
12
|
-
order: number;
|
|
13
|
-
}[];
|
|
9
|
+
content(options: import("type-fest").JsonValue, tree: import("mdast").Root): Promise<string>;
|
|
10
|
+
order: number;
|
|
14
11
|
};
|
|
15
12
|
tldraw: {
|
|
16
13
|
content(options?: import("type-fest").JsonValue | undefined): Promise<string>;
|
|
@@ -43,6 +40,10 @@ declare const _default: {
|
|
|
43
40
|
}[];
|
|
44
41
|
order: number;
|
|
45
42
|
};
|
|
43
|
+
description: {
|
|
44
|
+
content(): Promise<string>;
|
|
45
|
+
order: number;
|
|
46
|
+
};
|
|
46
47
|
contributing: {
|
|
47
48
|
content(): Promise<string>;
|
|
48
49
|
order: number;
|
|
@@ -1,3 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Simple alias for `description` rule, to match nomenclature in
|
|
3
|
+
* [standard-readme](https://github.com/RichardLitt/standard-readme/blob/main/spec.md#short-description)
|
|
4
|
+
* spec.
|
|
5
|
+
*/
|
|
1
6
|
declare const _default: {
|
|
2
7
|
'short-description': {
|
|
3
8
|
content(): Promise<string>;
|
|
@@ -4,11 +4,8 @@
|
|
|
4
4
|
declare const _default: {
|
|
5
5
|
toc: {
|
|
6
6
|
applicationOrder: number;
|
|
7
|
-
content:
|
|
8
|
-
|
|
9
|
-
content(options: import("type-fest").JsonValue, tree: import("mdast").Root): Promise<string>;
|
|
10
|
-
order: number;
|
|
11
|
-
}[];
|
|
7
|
+
content(options: import("type-fest").JsonValue, tree: import("mdast").Root): Promise<string>;
|
|
8
|
+
order: number;
|
|
12
9
|
};
|
|
13
10
|
};
|
|
14
11
|
export default _default;
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "mdat",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.7",
|
|
4
4
|
"type": "module",
|
|
5
|
-
"description": "CLI tool and library
|
|
5
|
+
"description": "CLI tool and library implementing the Markdown Autophagic Template (MDAT) system. MDAT lets you use comments as dynamic content templates in Markdown files, making it easy to generate and update readme boilerplate.",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
8
8
|
"url": "git@github.com:kitschpatrol/mdat.git",
|
|
@@ -70,10 +70,10 @@
|
|
|
70
70
|
"which": "^4.0.0",
|
|
71
71
|
"yargs": "^17.7.2",
|
|
72
72
|
"zod": "^3.22.4",
|
|
73
|
-
"remark-mdat": "0.6.
|
|
73
|
+
"remark-mdat": "0.6.7"
|
|
74
74
|
},
|
|
75
75
|
"devDependencies": {
|
|
76
|
-
"@types/node": "^20.11.
|
|
76
|
+
"@types/node": "^20.11.24",
|
|
77
77
|
"@types/which": "^3.0.3",
|
|
78
78
|
"@types/yargs": "^17.0.32",
|
|
79
79
|
"tsup": "^8.0.2",
|
package/readme.md
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
[](https://npmjs.com/package/mdat)
|
|
8
8
|
[](https://opensource.org/licenses/MIT)
|
|
9
9
|
|
|
10
|
-
**CLI tool and library
|
|
10
|
+
**CLI tool and library implementing the Markdown Autophagic Template (MDAT) system. MDAT lets you use comments as dynamic content templates in Markdown files, making it easy to generate and update readme boilerplate.**
|
|
11
11
|
|
|
12
12
|
<!-- /header -->
|
|
13
13
|
|
|
@@ -39,7 +39,7 @@
|
|
|
39
39
|
|
|
40
40
|
## Overview
|
|
41
41
|
|
|
42
|
-
This is a CLI tool and library implementing the Markdown Autophagic Template (
|
|
42
|
+
This is a CLI tool and library implementing the Markdown Autophagic Template (MDAT) system, which makes it easy to automate the replacement of placeholder comments in Markdown documents with dynamic content from a variety of sources. The `mdat` command can also validate the structure and content of the Markdown document based on constraints specified in the expansion rules, and bundles numerous convenient expansion rules for working with `readme.md` files under the `mdat readme` subcommand.
|
|
43
43
|
|
|
44
44
|
<!-- tldraw src: "./assets/mdat-flow.tldr" -->
|
|
45
45
|
|
|
@@ -117,7 +117,7 @@ As [noted below](#similar-projects), there are several similar projects out ther
|
|
|
117
117
|
<!-- /title -->
|
|
118
118
|
```
|
|
119
119
|
|
|
120
|
-
(Optionally, you can specify a prefix if you want to mix "true" comments with
|
|
120
|
+
(Optionally, you can specify a prefix if you want to mix "true" comments with MDAT content placeholder comments.)
|
|
121
121
|
|
|
122
122
|
2. **Single-comment placeholders**
|
|
123
123
|
|
|
@@ -183,11 +183,11 @@ As [noted below](#similar-projects), there are several similar projects out ther
|
|
|
183
183
|
|
|
184
184
|
This scales all the way up to some of the [more](./src/lib/readme/rules/table-of-contents.ts) [elaborate](./src/lib/readme/rules/cli-help) rules found in the `mdat readme` subcommand.
|
|
185
185
|
|
|
186
|
-
You can also treat any JSON file as a rule set.
|
|
186
|
+
You can also treat any JSON file as a rule set. MDAT will flatten it to allow any dot-notated key path to become a placeholder comment keyword.
|
|
187
187
|
|
|
188
188
|
5. **TypeScript native**
|
|
189
189
|
|
|
190
|
-
|
|
190
|
+
MDAT exports definitions for rule types, and configuration / rule sets may be written directly in TypeScript.
|
|
191
191
|
|
|
192
192
|
6. **Validation**
|
|
193
193
|
|
|
@@ -201,14 +201,14 @@ As [noted below](#similar-projects), there are several similar projects out ther
|
|
|
201
201
|
|
|
202
202
|
8. **Single-command readme workflow**
|
|
203
203
|
|
|
204
|
-
|
|
204
|
+
MDAT's most typical use case is streamlined with the `mdat readme` subcommand. Invoking this CLI command in your repo will automatically find your readme and your package.json and provide access to a collection of bundled expansion rules.
|
|
205
205
|
|
|
206
206
|
It also provides the `mdat readme init` subcommand with a selection of templates to kick off a fresh readme from scratch in a new project.
|
|
207
207
|
|
|
208
208
|
## Usage
|
|
209
209
|
|
|
210
210
|
> \[!WARNING]\
|
|
211
|
-
> **The
|
|
211
|
+
> **The MDAT CLI tool directly manipulates the contents of readme files, in close (and perhaps dangerous) proximity to your painstakingly crafted words.**
|
|
212
212
|
>
|
|
213
213
|
> Please make sure any text you care about is committed before running `mdat`, and never directly modify content inside of the comment expansion blocks.
|
|
214
214
|
>
|
|
@@ -220,7 +220,7 @@ As [noted below](#similar-projects), there are several similar projects out ther
|
|
|
220
220
|
|
|
221
221
|
#### Command: `mdat`
|
|
222
222
|
|
|
223
|
-
Work with
|
|
223
|
+
Work with MDAT placeholder comments in any Markdown file.
|
|
224
224
|
|
|
225
225
|
This section lists top-level commands for `mdat`.
|
|
226
226
|
|
|
@@ -232,18 +232,18 @@ Usage:
|
|
|
232
232
|
mdat [command]
|
|
233
233
|
```
|
|
234
234
|
|
|
235
|
-
| Command | Argument | Description
|
|
236
|
-
| ---------- | ----------------------- |
|
|
237
|
-
| `expand` | `<files..>` `[options]` | Expand
|
|
238
|
-
| `check` | `<files..>` `[options]` | Validate a
|
|
239
|
-
| `collapse` | `<files..>` `[options]` | Collapse
|
|
240
|
-
| `readme` | `[command]` | Work with
|
|
235
|
+
| Command | Argument | Description |
|
|
236
|
+
| ---------- | ----------------------- | -------------------------------------------------------------- |
|
|
237
|
+
| `expand` | `<files..>` `[options]` | Expand MDAT placeholder comments. _(Default command.)_ |
|
|
238
|
+
| `check` | `<files..>` `[options]` | Validate a Markdown file containing MDAT placeholder comments. |
|
|
239
|
+
| `collapse` | `<files..>` `[options]` | Collapse MDAT placeholder comments. |
|
|
240
|
+
| `readme` | `[command]` | Work with MDAT comments in your readme.md. |
|
|
241
241
|
|
|
242
242
|
_See the sections below for more information on each subcommand._
|
|
243
243
|
|
|
244
244
|
#### Subcommand: `mdat expand`
|
|
245
245
|
|
|
246
|
-
Expand
|
|
246
|
+
Expand MDAT placeholder comments.
|
|
247
247
|
|
|
248
248
|
Usage:
|
|
249
249
|
|
|
@@ -251,26 +251,26 @@ Usage:
|
|
|
251
251
|
mdat expand <files..> [options]
|
|
252
252
|
```
|
|
253
253
|
|
|
254
|
-
| Positional Argument | Description
|
|
255
|
-
| ------------------- |
|
|
256
|
-
| `files` | Markdown file(s) with
|
|
257
|
-
|
|
258
|
-
| Option | Alias | Description
|
|
259
|
-
| ----------- | ----- |
|
|
260
|
-
| `--config` | | Path(s) to files containing
|
|
261
|
-
| `--rules` | `-r` | Path(s) to files containing
|
|
262
|
-
| `--output` | `-o` | Output file directory.
|
|
263
|
-
| `--name` | `-n` | Output file name.
|
|
264
|
-
| `--meta` | `-m` | Embed an extra comment at the top of the generated Markdown warning editors that certain sections of the document have been generated dynamically.
|
|
265
|
-
| `--prefix` | | Require a string prefix before all comments to be considered for expansion. Useful if you have a bunch of non
|
|
266
|
-
| `--print` | | Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options.
|
|
267
|
-
| `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection.
|
|
268
|
-
| `--help` | `-h` | Show help
|
|
269
|
-
| `--version` | `-v` | Show version number
|
|
254
|
+
| Positional Argument | Description | Type |
|
|
255
|
+
| ------------------- | -------------------------------------------------------------- | -------- |
|
|
256
|
+
| `files` | Markdown file(s) with MDAT placeholder comments. _(Required.)_ | `string` |
|
|
257
|
+
|
|
258
|
+
| Option | Alias | Description | Type | Default |
|
|
259
|
+
| ----------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
|
|
260
|
+
| `--config` | | Path(s) to files containing MDAT configuration. | `array` | Configuration is loaded if found from the usual places, or defaults are used. |
|
|
261
|
+
| `--rules` | `-r` | Path(s) to files containing MDAT comment expansion rules. | `array` | |
|
|
262
|
+
| `--output` | `-o` | Output file directory. | `string` | Same directory as input file. |
|
|
263
|
+
| `--name` | `-n` | Output file name. | `string` | Same name as input file. Overwrites the input file. |
|
|
264
|
+
| `--meta` | `-m` | Embed an extra comment at the top of the generated Markdown warning editors that certain sections of the document have been generated dynamically. | `boolean` | |
|
|
265
|
+
| `--prefix` | | Require a string prefix before all comments to be considered for expansion. Useful if you have a bunch of non-MDAT comments in your Markdown file, or if you're willing to trade some verbosity for safety. | `string` | |
|
|
266
|
+
| `--print` | | Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options. | `boolean` | |
|
|
267
|
+
| `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` | |
|
|
268
|
+
| `--help` | `-h` | Show help | `boolean` | |
|
|
269
|
+
| `--version` | `-v` | Show version number | `boolean` | |
|
|
270
270
|
|
|
271
271
|
#### Subcommand: `mdat check`
|
|
272
272
|
|
|
273
|
-
Validate a
|
|
273
|
+
Validate a Markdown file containing MDAT placeholder comments.
|
|
274
274
|
|
|
275
275
|
Usage:
|
|
276
276
|
|
|
@@ -278,23 +278,23 @@ Usage:
|
|
|
278
278
|
mdat check <files..> [options]
|
|
279
279
|
```
|
|
280
280
|
|
|
281
|
-
| Positional Argument | Description
|
|
282
|
-
| ------------------- |
|
|
283
|
-
| `files` | Markdown file(s) with
|
|
281
|
+
| Positional Argument | Description | Type |
|
|
282
|
+
| ------------------- | -------------------------------------------------------------- | -------- |
|
|
283
|
+
| `files` | Markdown file(s) with MDAT placeholder comments. _(Required.)_ | `string` |
|
|
284
284
|
|
|
285
|
-
| Option | Alias | Description
|
|
286
|
-
| ----------- | ----- |
|
|
287
|
-
| `--config` | | Path(s) to files containing
|
|
288
|
-
| `--rules` | `-r` | Path(s) to files containing
|
|
289
|
-
| `--meta` | `-m` | Embed an extra comment at the top of the generated Markdown warning editors that certain sections of the document have been generated dynamically.
|
|
290
|
-
| `--prefix` | | Require a string prefix before all comments to be considered for expansion. Useful if you have a bunch of non
|
|
291
|
-
| `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection.
|
|
292
|
-
| `--help` | `-h` | Show help
|
|
293
|
-
| `--version` | `-v` | Show version number
|
|
285
|
+
| Option | Alias | Description | Type | Default |
|
|
286
|
+
| ----------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
|
|
287
|
+
| `--config` | | Path(s) to files containing MDAT configuration. | `array` | Configuration is loaded if found from the usual places, or defaults are used. |
|
|
288
|
+
| `--rules` | `-r` | Path(s) to files containing MDAT comment expansion rules. | `array` | |
|
|
289
|
+
| `--meta` | `-m` | Embed an extra comment at the top of the generated Markdown warning editors that certain sections of the document have been generated dynamically. | `boolean` | |
|
|
290
|
+
| `--prefix` | | Require a string prefix before all comments to be considered for expansion. Useful if you have a bunch of non-MDAT comments in your Markdown file, or if you're willing to trade some verbosity for safety. | `string` | |
|
|
291
|
+
| `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` | |
|
|
292
|
+
| `--help` | `-h` | Show help | `boolean` | |
|
|
293
|
+
| `--version` | `-v` | Show version number | `boolean` | |
|
|
294
294
|
|
|
295
295
|
#### Subcommand: `mdat collapse`
|
|
296
296
|
|
|
297
|
-
Collapse
|
|
297
|
+
Collapse MDAT placeholder comments.
|
|
298
298
|
|
|
299
299
|
Usage:
|
|
300
300
|
|
|
@@ -302,24 +302,24 @@ Usage:
|
|
|
302
302
|
mdat collapse <files..> [options]
|
|
303
303
|
```
|
|
304
304
|
|
|
305
|
-
| Positional Argument | Description
|
|
306
|
-
| ------------------- |
|
|
307
|
-
| `files` | Markdown file(s) with
|
|
308
|
-
|
|
309
|
-
| Option | Alias | Description
|
|
310
|
-
| ----------- | ----- |
|
|
311
|
-
| `--config` | | Path(s) to files containing
|
|
312
|
-
| `--output` | `-o` | Output file directory.
|
|
313
|
-
| `--name` | `-n` | Output file name.
|
|
314
|
-
| `--prefix` | | Require a string prefix before all comments to be considered for expansion. Useful if you have a bunch of non
|
|
315
|
-
| `--print` | | Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options.
|
|
316
|
-
| `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection.
|
|
317
|
-
| `--help` | `-h` | Show help
|
|
318
|
-
| `--version` | `-v` | Show version number
|
|
305
|
+
| Positional Argument | Description | Type |
|
|
306
|
+
| ------------------- | -------------------------------------------------------------- | -------- |
|
|
307
|
+
| `files` | Markdown file(s) with MDAT placeholder comments. _(Required.)_ | `string` |
|
|
308
|
+
|
|
309
|
+
| Option | Alias | Description | Type | Default |
|
|
310
|
+
| ----------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
|
|
311
|
+
| `--config` | | Path(s) to files containing MDAT configuration. | `array` | Configuration is loaded if found from the usual places, or defaults are used. |
|
|
312
|
+
| `--output` | `-o` | Output file directory. | `string` | Same directory as input file. |
|
|
313
|
+
| `--name` | `-n` | Output file name. | `string` | Same name as input file. Overwrites the input file. |
|
|
314
|
+
| `--prefix` | | Require a string prefix before all comments to be considered for expansion. Useful if you have a bunch of non-MDAT comments in your Markdown file, or if you're willing to trade some verbosity for safety. | `string` | |
|
|
315
|
+
| `--print` | | Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options. | `boolean` | |
|
|
316
|
+
| `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` | |
|
|
317
|
+
| `--help` | `-h` | Show help | `boolean` | |
|
|
318
|
+
| `--version` | `-v` | Show version number | `boolean` | |
|
|
319
319
|
|
|
320
320
|
#### Subcommand: `mdat readme`
|
|
321
321
|
|
|
322
|
-
Work with
|
|
322
|
+
Work with MDAT comments in your readme.md.
|
|
323
323
|
|
|
324
324
|
This section lists top-level commands for `mdat readme`.
|
|
325
325
|
|
|
@@ -331,18 +331,18 @@ Usage:
|
|
|
331
331
|
mdat readme [command]
|
|
332
332
|
```
|
|
333
333
|
|
|
334
|
-
| Command | Argument | Description
|
|
335
|
-
| ----------------- | ----------------------- |
|
|
336
|
-
| `readme expand` | `[files..]` `[options]` | Expand
|
|
337
|
-
| `readme check` | `[files..]` `[options]` | Validate
|
|
338
|
-
| `readme collapse` | `[files..]` `[options]` | Collapse
|
|
339
|
-
| `readme init` | `[options]` | Interactively create a new readme.md file with sensible default
|
|
334
|
+
| Command | Argument | Description |
|
|
335
|
+
| ----------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
|
336
|
+
| `readme expand` | `[files..]` `[options]` | Expand MDAT comment placeholders in your readme.md using a collection of helpful built-in expansion rules. _(Default command.)_ |
|
|
337
|
+
| `readme check` | `[files..]` `[options]` | Validate MDAT placeholder comments in your readme.md. |
|
|
338
|
+
| `readme collapse` | `[files..]` `[options]` | Collapse MDAT placeholder comments in your readme.md. |
|
|
339
|
+
| `readme init` | `[options]` | Interactively create a new readme.md file with sensible default MDAT comment placeholders. |
|
|
340
340
|
|
|
341
341
|
_See the sections below for more information on each subcommand._
|
|
342
342
|
|
|
343
343
|
#### Subcommand: `mdat readme expand`
|
|
344
344
|
|
|
345
|
-
Expand
|
|
345
|
+
Expand MDAT comment placeholders in your readme.md using a collection of helpful built-in expansion rules.
|
|
346
346
|
|
|
347
347
|
Usage:
|
|
348
348
|
|
|
@@ -350,28 +350,28 @@ Usage:
|
|
|
350
350
|
mdat readme expand [files..] [options]
|
|
351
351
|
```
|
|
352
352
|
|
|
353
|
-
| Positional Argument | Description
|
|
354
|
-
| ------------------- |
|
|
355
|
-
| `files` | Readme file(s) with
|
|
356
|
-
|
|
357
|
-
| Option | Alias | Description
|
|
358
|
-
| ----------- | ----- |
|
|
359
|
-
| `--config` | | Path(s) to files containing
|
|
360
|
-
| `--rules` | `-r` | Path(s) to files containing
|
|
361
|
-
| `--output` | `-o` | Output file directory.
|
|
362
|
-
| `--name` | `-n` | Output file name.
|
|
363
|
-
| `--package` | | Path to the package.json file to use to populate the readme.
|
|
364
|
-
| `--assets` | | Path to find and save readme-related assets.
|
|
365
|
-
| `--prefix` | | Require a string prefix before all comments to be considered for expansion. Useful if you have a bunch of non
|
|
366
|
-
| `--meta` | `-m` | Embed an extra comment at the top of the generated Markdown warning editors that certain sections of the document have been generated dynamically.
|
|
367
|
-
| `--print` | | Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options.
|
|
368
|
-
| `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection.
|
|
369
|
-
| `--help` | `-h` | Show help
|
|
370
|
-
| `--version` | `-v` | Show version number
|
|
353
|
+
| Positional Argument | Description | Type |
|
|
354
|
+
| ------------------- | ----------------------------------------------------------------------------------------------------------------- | -------- |
|
|
355
|
+
| `files` | Readme file(s) with MDAT placeholder comments. If not provided, the closest readme.md file is used. _(Optional.)_ | `string` |
|
|
356
|
+
|
|
357
|
+
| Option | Alias | Description | Type | Default |
|
|
358
|
+
| ----------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
|
|
359
|
+
| `--config` | | Path(s) to files containing MDAT configuration. | `array` | Configuration is loaded if found from the usual places, or defaults are used. |
|
|
360
|
+
| `--rules` | `-r` | Path(s) to files containing MDAT comment expansion rules. | `array` | |
|
|
361
|
+
| `--output` | `-o` | Output file directory. | `string` | Same directory as input file. |
|
|
362
|
+
| `--name` | `-n` | Output file name. | `string` | Same name as input file. Overwrites the input file. |
|
|
363
|
+
| `--package` | | Path to the package.json file to use to populate the readme. | `string` | The closest package.json file is used by default. |
|
|
364
|
+
| `--assets` | | Path to find and save readme-related assets. | `string` | `./assets` |
|
|
365
|
+
| `--prefix` | | Require a string prefix before all comments to be considered for expansion. Useful if you have a bunch of non-MDAT comments in your Markdown file, or if you're willing to trade some verbosity for safety. | `string` | |
|
|
366
|
+
| `--meta` | `-m` | Embed an extra comment at the top of the generated Markdown warning editors that certain sections of the document have been generated dynamically. | `boolean` | |
|
|
367
|
+
| `--print` | | Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options. | `boolean` | |
|
|
368
|
+
| `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` | |
|
|
369
|
+
| `--help` | `-h` | Show help | `boolean` | |
|
|
370
|
+
| `--version` | `-v` | Show version number | `boolean` | |
|
|
371
371
|
|
|
372
372
|
#### Subcommand: `mdat readme check`
|
|
373
373
|
|
|
374
|
-
Validate
|
|
374
|
+
Validate MDAT placeholder comments in your readme.md.
|
|
375
375
|
|
|
376
376
|
Usage:
|
|
377
377
|
|
|
@@ -379,25 +379,25 @@ Usage:
|
|
|
379
379
|
mdat readme check [files..] [options]
|
|
380
380
|
```
|
|
381
381
|
|
|
382
|
-
| Positional Argument | Description
|
|
383
|
-
| ------------------- |
|
|
384
|
-
| `files` | Readme file(s) with
|
|
385
|
-
|
|
386
|
-
| Option | Alias | Description
|
|
387
|
-
| ----------- | ----- |
|
|
388
|
-
| `--config` | | Path(s) to files containing
|
|
389
|
-
| `--rules` | `-r` | Path(s) to files containing
|
|
390
|
-
| `--package` | | Path to the package.json file to use to populate the readme.
|
|
391
|
-
| `--assets` | | Path to find and save readme-related assets.
|
|
392
|
-
| `--prefix` | | Require a string prefix before all comments to be considered for expansion. Useful if you have a bunch of non
|
|
393
|
-
| `--meta` | `-m` | Embed an extra comment at the top of the generated Markdown warning editors that certain sections of the document have been generated dynamically.
|
|
394
|
-
| `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection.
|
|
395
|
-
| `--help` | `-h` | Show help
|
|
396
|
-
| `--version` | `-v` | Show version number
|
|
382
|
+
| Positional Argument | Description | Type |
|
|
383
|
+
| ------------------- | ----------------------------------------------------------------------------------------------------------------- | -------- |
|
|
384
|
+
| `files` | Readme file(s) with MDAT placeholder comments. If not provided, the closest readme.md file is used. _(Optional.)_ | `string` |
|
|
385
|
+
|
|
386
|
+
| Option | Alias | Description | Type | Default |
|
|
387
|
+
| ----------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
|
|
388
|
+
| `--config` | | Path(s) to files containing MDAT configuration. | `array` | Configuration is loaded if found from the usual places, or defaults are used. |
|
|
389
|
+
| `--rules` | `-r` | Path(s) to files containing MDAT comment expansion rules. | `array` | |
|
|
390
|
+
| `--package` | | Path to the package.json file to use to populate the readme. | `string` | The closest package.json file is used by default. |
|
|
391
|
+
| `--assets` | | Path to find and save readme-related assets. | `string` | `./assets` |
|
|
392
|
+
| `--prefix` | | Require a string prefix before all comments to be considered for expansion. Useful if you have a bunch of non-MDAT comments in your Markdown file, or if you're willing to trade some verbosity for safety. | `string` | |
|
|
393
|
+
| `--meta` | `-m` | Embed an extra comment at the top of the generated Markdown warning editors that certain sections of the document have been generated dynamically. | `boolean` | |
|
|
394
|
+
| `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` | |
|
|
395
|
+
| `--help` | `-h` | Show help | `boolean` | |
|
|
396
|
+
| `--version` | `-v` | Show version number | `boolean` | |
|
|
397
397
|
|
|
398
398
|
#### Subcommand: `mdat readme collapse`
|
|
399
399
|
|
|
400
|
-
Collapse
|
|
400
|
+
Collapse MDAT placeholder comments in your readme.md.
|
|
401
401
|
|
|
402
402
|
Usage:
|
|
403
403
|
|
|
@@ -405,24 +405,24 @@ Usage:
|
|
|
405
405
|
mdat readme collapse [files..] [options]
|
|
406
406
|
```
|
|
407
407
|
|
|
408
|
-
| Positional Argument | Description
|
|
409
|
-
| ------------------- |
|
|
410
|
-
| `files` | Readme file(s) with
|
|
411
|
-
|
|
412
|
-
| Option | Alias | Description
|
|
413
|
-
| ----------- | ----- |
|
|
414
|
-
| `--output` | `-o` | Output file directory.
|
|
415
|
-
| `--name` | `-n` | Output file name.
|
|
416
|
-
| `--print` | | Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options.
|
|
417
|
-
| `--config` | | Path(s) to files containing
|
|
418
|
-
| `--prefix` | | Require a string prefix before all comments to be considered for expansion. Useful if you have a bunch of non
|
|
419
|
-
| `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection.
|
|
420
|
-
| `--help` | `-h` | Show help
|
|
421
|
-
| `--version` | `-v` | Show version number
|
|
408
|
+
| Positional Argument | Description | Type |
|
|
409
|
+
| ------------------- | ----------------------------------------------------------------------------------------------------------------- | -------- |
|
|
410
|
+
| `files` | Readme file(s) with MDAT placeholder comments. If not provided, the closest readme.md file is used. _(Optional.)_ | `string` |
|
|
411
|
+
|
|
412
|
+
| Option | Alias | Description | Type | Default |
|
|
413
|
+
| ----------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
|
|
414
|
+
| `--output` | `-o` | Output file directory. | `string` | Same directory as input file. |
|
|
415
|
+
| `--name` | `-n` | Output file name. | `string` | Same name as input file. Overwrites the input file. |
|
|
416
|
+
| `--print` | | Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options. | `boolean` | |
|
|
417
|
+
| `--config` | | Path(s) to files containing MDAT configuration. | `array` | Configuration is loaded if found from the usual places, or defaults are used. |
|
|
418
|
+
| `--prefix` | | Require a string prefix before all comments to be considered for expansion. Useful if you have a bunch of non-MDAT comments in your Markdown file, or if you're willing to trade some verbosity for safety. | `string` | |
|
|
419
|
+
| `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` | |
|
|
420
|
+
| `--help` | `-h` | Show help | `boolean` | |
|
|
421
|
+
| `--version` | `-v` | Show version number | `boolean` | |
|
|
422
422
|
|
|
423
423
|
#### Subcommand: `mdat readme init`
|
|
424
424
|
|
|
425
|
-
Interactively create a new readme.md file with sensible default
|
|
425
|
+
Interactively create a new readme.md file with sensible default MDAT comment placeholders.
|
|
426
426
|
|
|
427
427
|
Usage:
|
|
428
428
|
|
|
@@ -436,7 +436,7 @@ mdat readme init [options]
|
|
|
436
436
|
| `--overwrite` | | Replace an existing readme file if one is found. | `boolean` | `false`, if an existing readme is found, don't touch it. |
|
|
437
437
|
| `--output` | `-o` | Output file directory. | `string` | Same directory as input file. |
|
|
438
438
|
| `--expand` | `-e` | Automatically run `mdat readme` immediately after creating the readme template. | `boolean` | `true` |
|
|
439
|
-
| `--template` | `-t` | Specify a template to use for the new readme. | `string` | "
|
|
439
|
+
| `--template` | `-t` | Specify a template to use for the new readme. | `string` | "MDAT Readme" |
|
|
440
440
|
| `--compound` | `-c` | Use compound comment version of the template to replace several individual comment placeholders where possible. This combines things like `<!-- title -->`, `<!-- badges -->`, etc. in a single `<!-- header -->` comment. It's less clutter when you're editing, but it's also less explicit. The final readme.md output is identical. | `boolean` | `true` |
|
|
441
441
|
| `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` | |
|
|
442
442
|
| `--help` | `-h` | Show help | `boolean` | |
|
|
@@ -444,7 +444,7 @@ mdat readme init [options]
|
|
|
444
444
|
|
|
445
445
|
<!-- /cli-help -->
|
|
446
446
|
|
|
447
|
-
_Meta note: The entire section above was generated automatically by the [`<!-- cli-help -->`](./src/lib/readme/rules/cli-help/index.ts) mdat expansion rule provided in `mdat readme` subcommand. It dynamically parses the output from `mdat --help` into a
|
|
447
|
+
_Meta note: The entire section above was generated automatically by the [`<!-- cli-help -->`](./src/lib/readme/rules/cli-help/index.ts) mdat expansion rule provided in `mdat readme` subcommand. It dynamically parses the output from `mdat --help` into a Markdown table, recursively calling `--help` on subcommands to build a tidy representation of the help output._
|
|
448
448
|
|
|
449
449
|
#### Examples
|
|
450
450
|
|
|
@@ -486,7 +486,7 @@ mdat --rules 'rules.ts' 'more-rules.js' 'yet-more-rules.json'
|
|
|
486
486
|
|
|
487
487
|
##### Readme expansion
|
|
488
488
|
|
|
489
|
-
Expand
|
|
489
|
+
Expand MDAT comments in your readme.md:
|
|
490
490
|
|
|
491
491
|
```sh
|
|
492
492
|
mdat readme
|
|
@@ -669,10 +669,12 @@ See the [Examples section](../remark-mdat/readme.md#examples) of the `remark-mda
|
|
|
669
669
|
|
|
670
670
|
Generates badges based on `package.json`. Currently only supports license and NPM version badges.
|
|
671
671
|
|
|
672
|
-
- ###### `<!--
|
|
672
|
+
- ###### `<!-- description -->`
|
|
673
673
|
|
|
674
674
|
The `description` field from `package.json`.
|
|
675
675
|
|
|
676
|
+
This rule is also aliased under the `<!-- short-description -->` keyword, for consistency with the [standard-readme](https://github.com/RichardLitt/standard-readme/blob/main/spec.md#short-description) spec.
|
|
677
|
+
|
|
676
678
|
- ###### `<!-- table-of-contents -->`
|
|
677
679
|
|
|
678
680
|
A table of contents automatically generated by [mdast-util-toc](https://github.com/syntax-tree/mdast-util-toc).
|
|
@@ -735,9 +737,9 @@ Compound rules combine several stand-alone rules under a single keyword, which c
|
|
|
735
737
|
|
|
736
738
|
#### Bundled templates
|
|
737
739
|
|
|
738
|
-
The `init` command provides a number of "starter readme" templates incorporating
|
|
740
|
+
The `init` command provides a number of "starter readme" templates incorporating MDAT comment placeholders:
|
|
739
741
|
|
|
740
|
-
- #####
|
|
742
|
+
- ##### MDAT Readme
|
|
741
743
|
|
|
742
744
|
The house style. An expansive starting point. Prune to your context and taste. The readme files in this monorepo started from this template.
|
|
743
745
|
|
|
@@ -757,7 +759,7 @@ A package definition file like `package.json` is the canonical "single source of
|
|
|
757
759
|
|
|
758
760
|
You could set up a separate readme template file and use one of a to generate your readme, but then you'd still have to wire up data ingestion and deal with and the cognitive clutter of a second half-baked readme in your repo.
|
|
759
761
|
|
|
760
|
-
|
|
762
|
+
MDAT solves this tedium by committing a minor sacrilege: It allows comments in Markdown files to become placeholders for dynamic content, overwriting themselves in place with content pulled from around your repo. When `mdat` is run against the file, specific comments are expanded with content from elsewhere, the file is updated in-situ.
|
|
761
763
|
|
|
762
764
|
I wrote it for use in my own projects, but if someone else finds it useful, that's great.
|
|
763
765
|
|
|
@@ -769,10 +771,10 @@ This has been done several times before:
|
|
|
769
771
|
Goes way back.
|
|
770
772
|
|
|
771
773
|
- David Wells' [Markdown Magic](https://github.com/DavidWells/markdown-magic)\
|
|
772
|
-
I somehow missed the existence of this one until after building out
|
|
774
|
+
I somehow missed the existence of this one until after building out MDAT. It's very similar conceptually, and has a nice ecosystem of plugins.
|
|
773
775
|
|
|
774
776
|
- Titus Wormer's [mdast-zone](https://github.com/syntax-tree/mdast-zone)\
|
|
775
|
-
Allows comments to be used as ranges or markers in Markdown files. Similar tree parsing and walking strategy to
|
|
777
|
+
Allows comments to be used as ranges or markers in Markdown files. Similar tree parsing and walking strategy to MDAT. Mdast-zone uses different syntax for arguments, and requires both opening and closing tags to be present for expansion to occur.
|
|
776
778
|
|
|
777
779
|
- lillallol's [md-in-place](https://www.npmjs.com/package/md-in-place)
|
|
778
780
|
|
|
@@ -798,7 +800,7 @@ Recommended workflow integration approach:
|
|
|
798
800
|
|
|
799
801
|
## Acknowledgments
|
|
800
802
|
|
|
801
|
-
- The [unified](https://unifiedjs.com), [remark](https://remark.js.org), and [unist](https://github.com/syntax-tree/unist) / [mdast](https://github.com/syntax-tree/mdast) ecosystem is powerful and well-architected.
|
|
803
|
+
- The [unified](https://unifiedjs.com), [remark](https://remark.js.org), and [unist](https://github.com/syntax-tree/unist) / [mdast](https://github.com/syntax-tree/mdast) ecosystem is powerful and well-architected. MDAT relies on it to do the the heavy lifting in of parsing, transforming, and restoring the Markdown to string form.
|
|
802
804
|
|
|
803
805
|
- Richard Litt's [Standard Readme](https://github.com/RichardLitt/standard-readme) specification inspired some of the templates available in `mdat readme init`.
|
|
804
806
|
|