mdat 0.5.2 → 0.6.0
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 +13 -12
- package/dist/index.js +13 -12
- package/dist/readme/rules/cli-help/index.d.ts +1 -1
- package/dist/readme/rules/index.d.ts +1 -1
- package/package.json +10 -10
- package/readme.md +92 -102
package/bin/cli.js
CHANGED
|
@@ -1,35 +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
|
|
5
|
-
`)},order:3,required:!1}};import{globby as qn}from"globby";import re from"node:path";import{isFile as zn}from"path-type";import{readPackage as Gn}from"read-pkg";import{z as
|
|
2
|
+
import{defaultLoaders as vn}from"cosmiconfig";function xe(t,e){let n=vn[".json"],i=n(t,e);return ht(i)}function ht(t,e="",n={}){for(let[i,o]of Object.entries(t)){let r=e?`${e}.${i}`:i;typeof o=="object"&&o!==null&&!Array.isArray(o)?ht(o,r,n):o===null?n[r]="null":n[r]=o.toString()}return n}import Tn from"node:fs";import O from"node:path";import{packageUp as $n}from"package-up";import{isFileSync as yt}from"path-type";import Nn from"untildify";function An(t,e){let n=e===0?1:Math.floor(Math.log10(Math.abs(e))+1);return t.toString().padStart(n,"0")}function bt(t,e,n,i){let o=[];for(let[r,a]of t.entries()){let s=n&&t.length>1?`-${An(r+1,t.length+1)}`:"",d=_n(a,e,n,i,s);o.push(d)}return o}function _n(t,e,n,i,o=""){let r=wt(t),a=e?wt(e):void 0;if(!yt(r))throw new Error(`Input file not found: "${r}"`);if(a){if(yt(a))throw new Error(`Output path must be a directory, received a file path: "${a}"`);Tn.mkdirSync(a,{recursive:!0})}let s=n?O.basename(n,O.extname(n)):O.basename(r,O.extname(r)),d=`.${i??(n&&O.extname(n)!==""?O.extname(n):O.extname(t)===""?"":O.extname(t))}`,m=`${s}${o}${d}`,c=a??O.dirname(r);return{input:r,name:m,output:c}}function wt(t){return Nn(t)}async function X(){return $n()}function Q(t){return t==null?[]:Array.isArray(t)?t:[t]}import Ct from"chalk";import{cosmiconfig as Pt}from"cosmiconfig";import In from"node:fs/promises";import St from"node:path";import Mn from"plur";import{readPackage as Dn}from"read-pkg";import{deepMergeDefined as Ee,log as b,optionsSchema as jn,rulesSchema as Fn}from"remark-mdat";import{z as Le}from"zod";var Ot=jn.merge(Le.object({assetsPath:Le.string().optional(),packageFile:Le.string().optional()})).describe("Config Extension");async function L(t){let{additionalConfig:e,additionalRules:n,searchFrom:i}=t??{},o={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=Pt("mdat"),a=await r.search(i);if(a){let{config:s,filepath:d}=a;b.info(`Using config from "${d}"`);let m=Rt(s,Ot);m&&(o=Ee(o,m))}if(e!==void 0){let s=Array.isArray(e)?e:[e];for(let d of s){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=Rt(m,Ot);c!==void 0&&(o=Ee(o,c))}}if(n!==void 0){let s=Array.isArray(n)?n:[n],d=Pt("mdat",{loaders:{".json":xe}});for(let m of s){let c;if(typeof m=="string"){let g;if(St.basename(m).endsWith("package.json")){let M=await In.readFile(m,"utf8");g={config:xe(m,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=Un(c,Fn);p!==void 0&&(o=Ee(o,p))}}if(o.rules){let s=Object.keys(o.rules).sort().map(d=>`"${Ct.bold.green(d)}"`);b.info(`Loaded ${Ct.bold(s.length)} mdat comment expansion ${Mn("rule",s.length)}:`);for(let d of s)b.info(` ${d}`)}else b.error("No rules loaded from additional configurations or rules, using default.");return ee=o,o}function Un(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 Rt(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 Dn({cwd:St.dirname(t)}),ve===void 0)throw new Error("No package.json found");return ve}import{remark as Te}from"remark";import $e from"remark-gfm";import{mdatCheck as Vn,mdatClean as kt,mdatExpand as Bn,mdatSplit as xt}from"remark-mdat";import{read as Jn}from"to-vfile";import{VFile as Ci}from"vfile";async function S(t,e,n,i,o,r,a){let s=await e({additionalConfig:r,additionalRules:a});r=s;let d=Q(t),m=bt(d,o,i,"md"),c=[],p=n(s);for(let{input:g,name:y,output:w}of m){let M=await Jn(g),Z=await p.process(M);Z.dirname=w,Z.basename=y,c.push(Z)}return c}function te(t){return Te().use({settings:{bullet:"-",emphasis:"_"}}).use($e).use(()=>async function(n,i){xt(n,i),kt(n,i,t),await Bn(n,i,t)})}function ne(t){return Te().use({settings:{bullet:"-",emphasis:"_"}}).use($e).use(()=>function(n,i){xt(n,i),kt(n,i,t)})}function oe(t){return Te().use({settings:{bullet:"-",emphasis:"_"}}).use($e).use(()=>async function(n,i){await Vn(n,i,{...t,paranoid:!1})})}async function Et(t,e,n,i,o){return S(t,L,te,e,n,i,o)}async function Lt(t,e,n,i,o){return S(t,L,oe,e,n,i,o)}async function vt(t,e,n,i,o){return S(t,L,ne,e,n,i,o)}import{z as v}from"zod";var ie={badges:{async content(t){var a;let e=v.object({custom:v.record(v.object({image:v.string(),link:v.string()})).optional(),npm:v.array(v.string()).optional()}).optional().parse(t),n=await h(),{name:i}=n,o=[];if(!n.private&&((a=n.publishConfig)==null?void 0:a.access)==="public"&&o.push(`[](https://npmjs.com/package/${i})`),(e==null?void 0:e.npm)!==void 0)for(let s of e.npm)o.push(`[](https://npmjs.com/package/${s})`);let{license:r}=n;if(r!==void 0&&o.push(`[](https://opensource.org/licenses/${r})`),(e==null?void 0:e.custom)!==void 0)for(let[s,{image:d,link:m}]of Object.entries(e.custom))o.push(`[](${m})`);return o.join(`
|
|
5
|
+
`)},order:3,required:!1}};import{globby as qn}from"globby";import re from"node:path";import{isFile as zn}from"path-type";import{readPackage as Gn}from"read-pkg";import{z as Ne}from"zod";var ae={banner:{async content(t){let e=Ne.object({alt:Ne.string().optional(),src:Ne.string().optional()}).optional().parse(t),{assetsPath:n,packageFile:i}=await P();if(i===void 0)throw new Error("No package.json found");let o=(e==null?void 0:e.src)??await Kn(n);if(o===void 0)throw new Error("Banner image not found at any typical location, consider adding something at ./assets/banner.webp");if(!Tt(o)&&!await zn(o))throw new Error(`Banner image not found at "${o}"`);let r=(e==null?void 0:e.alt)??`${(await Gn({cwd:re.dirname(i)})).name} banner`;if(r===void 0||r==="undefined banner")throw new Error("Banner image alt text not available");return``},order:2}};async function Kn(t){let{packageFile:e}=await P();if(e===void 0)throw new Error("No package.json found");let n=re.dirname(e),i=t===void 0?[".","assets","media","readme-assets","readme-media","readme","images"]:[t],o=["banner","header","logo","readme","cover","screenshot","screenshots","demo","overview","image","hero"],r=["png","gif","jpg","jpeg","svg","webp"],a=await qn(i.map(s=>re.join(n,s)),{expandDirectories:{extensions:r,files:o}});if(a.length>0)return re.relative(process.cwd(),a[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 $t(t,e=Number.MAX_SAFE_INTEGER){let n=[],i=Wn(t,e);return n.push(Yn(i)),n.push(Zn(t,i)),i.hasMultipleSubcommands&&i.canRecurse&&n.push(Xn(i.fullCommandName)),i.defaultCommand&&n.push(Qn(i)),n.push(eo(t,i)),t.positionals&&!i.commandsOnly&&n.push(Ae(["Positional Argument","Description","Type","Default"],t.positionals.map(o=>[o.arguments?[o.arguments.map(r=>`\`${r}\``)].join(" "):"",`${o.description??""}${o.required?" _(Required.)_":" _(Optional.)_"}`,o.type?`\`${o.type}\``:"",o.defaultValue?o.defaultValue.includes(" ")?o.defaultValue:`\`${o.defaultValue}\``:""]))),t.commands&&n.push(Ae(["Command","Argument","Description"],t.commands.map(o=>{var r;return[`\`${o.commandName??(o.default?"[default]":"")}\``,o.arguments?(r=o.arguments)==null?void 0:r.map(a=>`\`${a}\``).join(" "):"",`${o.description??""}${o.default?" _(Default command.)_":""}`]}))),t.options&&!i.commandsOnly&&n.push(Ae(["Option","Alias","Argument","Description","Type","Default"],t.options.map(o=>[o.flags?o.flags.map(r=>`\`${r}\``).join(" "):"",o.aliases?o.aliases.map(r=>`\`${r}\``).join(" "):"",o.arguments?o.arguments.map(r=>`\`${r}\``).join(" "):"",o.description??"",o.type?`\`${o.type}\``:"",o.defaultValue?o.defaultValue.includes(" ")?o.defaultValue:`\`${o.defaultValue}\``:""]))),i.commandsOnly&&n.push("_See the sections below for more information on each subcommand._"),n.join(`
|
|
6
|
+
|
|
7
|
+
`)}function Wn(t,e){var m,c;let n=t.subcommandName===void 0,i=t.commands?t.commands.length>1:!1,o=e>1,r=(m=t.commands)==null?void 0:m.find(p=>p.default),a=(c=t.commands)==null?void 0:c.find(p=>p.commandName===void 0),s=`${t.commandName}${t.subcommandName?` ${t.subcommandName}`:""}`;return{canRecurse:o,commandsOnly:o&&i,defaultCommand:r,fullCommandName:s,hasMultipleSubcommands:i,isTopLevel:n,topLevelCommand:a}}function Yn(t){return`#### ${t.isTopLevel?"Command":"Subcommand"}: \`${t.fullCommandName}\``}function Zn(t,e){var n,i;return e.isTopLevel&&((n=e.topLevelCommand)!=null&&n.description)?(t.commands=(i=t.commands)==null?void 0:i.filter(o=>o!==e.topLevelCommand),e.topLevelCommand.description):t.description??""}function Xn(t){return`This section lists top-level commands for \`${t}\`.`}function Qn(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 eo(t,e){var i;let n=(i=e.topLevelCommand)!=null&&i.arguments?` ${e.topLevelCommand.arguments.join(" ")}`:`${t.arguments?` ${t.arguments.join(" ")}`:""}`;return`Usage:
|
|
6
8
|
|
|
7
|
-
`)}function Wn(t,e){var m,c;let n=t.subcommandName===void 0,i=t.commands?t.commands.length>1:!1,o=e>1,r=(m=t.commands)==null?void 0:m.find(p=>p.default),a=(c=t.commands)==null?void 0:c.find(p=>p.commandName===void 0),s=`${t.commandName}${t.subcommandName?` ${t.subcommandName}`:""}`;return{canRecurse:o,commandsOnly:o&&i,defaultCommand:r,fullCommandName:s,hasMultipleSubcommands:i,isTopLevel:n,topLevelCommand:a}}function Yn(t){return`#### ${t.isTopLevel?"Command":"Subcommand"}: \`${t.fullCommandName}\``}function Zn(t,e){var n,i;return e.isTopLevel&&((n=e.topLevelCommand)!=null&&n.description)?(t.commands=(i=t.commands)==null?void 0:i.filter(o=>o!==e.topLevelCommand),e.topLevelCommand.description):t.description??""}function Xn(t){return`This section lists top-level commands for \`${t}\`.`}function Qn(t){var e;return`If no command is provided, \`${t.fullCommandName} ${(e=t.defaultCommand)==null?void 0:e.commandName}\` is run by default.`}function eo(t,e){var i;let n=(i=e.topLevelCommand)!=null&&i.arguments?` ${e.topLevelCommand.arguments.join(" ")}`:`${t.arguments?` ${t.arguments.join(" ")}`:""}`;return`Usage:
|
|
8
9
|
\`\`\`txt
|
|
9
10
|
${e.fullCommandName}${n}
|
|
10
|
-
\`\`\``}function
|
|
11
|
+
\`\`\``}function Ae(t,e){let n=to(e);t=t.filter((o,r)=>!n.includes(r)),e=e.map(o=>o.filter((r,a)=>!n.includes(a)));let i="";i+=`| ${t.join(" | ")} |
|
|
11
12
|
`,i+=`| ${t.map(()=>"---").join(" | ")} |
|
|
12
13
|
`;for(let o of e)i+=`| ${o.join(" | ")} |
|
|
13
|
-
`;return i}function to(t){var i;let e=[],n=((i=t[0])==null?void 0:i.length)||0;for(let o=0;o<n;o++){let r=!0;for(let a of t)if(a[o]!==""){r=!1;break}r&&e.push(o)}return e}import{CstParser as no,Lexer as
|
|
14
|
+
`;return i}function to(t){var i;let e=[],n=((i=t[0])==null?void 0:i.length)||0;for(let o=0;o<n;o++){let r=!0;for(let a of t)if(a[o]!==""){r=!1;break}r&&e.push(o)}return e}import{CstParser as no,Lexer as R,createToken as f}from"chevrotain";var me=f({name:"flag",pattern:/--[\w-_]+/}),Me=f({longer_alt:me,name:"alias",pattern:/-[A-Za-z]/}),Nt=f({group:R.SKIPPED,name:"comma",pattern:/,/}),At=f({group:R.SKIPPED,name:"dollar",pattern:/\$/}),se=f({group:R.SKIPPED,name:"whiteSpace",pattern:/ /}),_t=f({group:R.SKIPPED,name:"newLine",pattern:/\n/}),De=f({name:"word",pattern:/\S+/}),H=f({name:"argument",pattern:/(<\S+>|\[.+])/}),je=f({name:"programDescription",pattern:/\w.+(?=\n\n {2}Usage)/}),It=f({group:R.SKIPPED,name:"startUsage",pattern:/ {2}Usage\n/,push_mode:"USAGE_MODE"}),Mt=f({group:R.SKIPPED,name:"endUsage",pattern:/\n/,pop_mode:!0}),Fe=f({name:"startOptions",pattern:/ {2}Options\n/,push_mode:"OPTIONS_MODE"}),Ue=f({name:"startRow",pattern:/ {4}/,push_mode:"ROW_MODE"}),Ve=f({name:"rowDescription",pattern:/\w.+/}),Dt=f({group:R.SKIPPED,name:"endRow",pattern:/\n/,pop_mode:!0}),jt=f({group:R.SKIPPED,name:"endOptions",pattern:/\n/,pop_mode:!0}),oo=new R({defaultMode:"DEFAULT_MODE",modes:{DEFAULT_MODE:[It,Fe,je,_t,se],OPTIONS_MODE:[jt,Ue],ROW_MODE:[Dt,Me,me,Nt,H,Ve,se],USAGE_MODE:[Mt,At,H,De,se]}}),io=[me,Me,Nt,At,se,_t,De,H,je,It,Mt,Fe,Ue,Ve,Dt,jt],_e=class extends no{programHelp=this.RULE("programHelp",()=>{this.CONSUME(je,{LABEL:"description"}),this.AT_LEAST_ONE(()=>{this.CONSUME(De,{LABEL:"commandName"})}),this.MANY(()=>{this.CONSUME(H)}),this.OPTION(()=>{this.SUBRULE(this.optionsSection)})});optionsSection=this.RULE("optionsSection",()=>{this.CONSUME(Fe),this.MANY(()=>{this.SUBRULE(this.sectionRow)})});sectionRow=this.RULE("sectionRow",()=>{this.CONSUME(Ue),this.MANY(()=>{this.OR([{ALT:()=>this.CONSUME(H)},{ALT:()=>this.CONSUME(Me)},{ALT:()=>this.CONSUME(me)},{ALT:()=>this.CONSUME(Ve,{LABEL:"description"})}])})});constructor(){super(io),this.performSelfAnalysis()}},J=new _e,Ie=class extends J.getBaseCstVisitorConstructor(){constructor(){super(),this.validateVisitor()}programHelp(e){let{command:n,subcommand:i}=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:i}}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(i=>n?this.clean(i.image):i.image).join(" ")}getArray(e){if(e!==void 0)return e.map(n=>n.image)}clean(e){return e.replaceAll(/^[\s[]*(default:)?\s*|[\s\]]*$/g,"")}},ro=new Ie;function Ft(t){let e=oo.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 i;try{i=ro.visit(n)}catch(o){if(o instanceof Error)throw new TypeError(`Errors visiting CLI command help text: ${String(o)}`)}if(i===void 0)throw new Error("Could not parse help string");return i}import{CstParser as ao,Lexer as T,createToken as l}from"chevrotain";var qe=l({name:"flag",pattern:/--[\w-_]+/}),ze=l({name:"alias",pattern:/-[A-Za-z]/}),Ut=l({group:T.SKIPPED,name:"comma",pattern:/,/}),D=l({name:"word",pattern:/\S+/}),z=l({name:"argument",pattern:/<\S+>|\[\S+]/}),Ge=l({name:"type",pattern:/\[(boolean|string|array)]/}),Ke=l({name:"defaultInfo",pattern:/\[default]/}),We=l({name:"required",pattern:/\[required]/}),Ye=l({name:"defaultInfoDescription",pattern:/\[default:\s.+?]/}),Ze=l({name:"choices",pattern:/\[choices:\s.+?]/}),Be=l({group:T.SKIPPED,name:"whiteSpace",pattern:/\s/}),Vt=l({group:T.SKIPPED,name:"startProgramDescription",pattern:/\n\n/,push_mode:"PROGRAM_DESCRIPTION_MODE"}),Xe=l({name:"programDescription",pattern:/.+/}),Bt=l({group:T.SKIPPED,name:"endProgramDescription",pattern:/\n\n/,pop_mode:!0}),Qe=l({name:"startOptionsSection",pattern:/Options:?\n/,push_mode:"SECTION_MODE"}),et=l({name:"startPositionalsSection",pattern:/Positionals:\n/,push_mode:"SECTION_MODE"}),tt=l({name:"startCommandsSection",pattern:/Commands:\n/,push_mode:"SECTION_MODE"}),nt=l({name:"startRow",pattern:/ {2,}/,push_mode:"ROW_MODE"}),ot=l({name:"rowDescription",pattern:/ {2}\w.+ {2}/}),it=l({name:"rowDescriptionTerminal",pattern:/ {2}\w.+/}),Jt=l({group:T.SKIPPED,name:"endRow",pattern:/\n/,pop_mode:!0}),Ht=l({group:T.SKIPPED,name:"endSection",pattern:/\n+/,pop_mode:!0}),so=new T({defaultMode:"DEFAULT_MODE",modes:{DEFAULT_MODE:[Qe,et,tt,Vt,z,D,Be],PROGRAM_DESCRIPTION_MODE:[Bt,Xe],ROW_MODE:[Jt,Ut,Ge,ot,it,Ye,Ke,We,Ze,qe,ze,z,D,Be],SECTION_MODE:[nt,Ht]}}),mo=[qe,ze,Ut,D,z,Ge,Ke,We,Ye,Ze,Be,Vt,Xe,Bt,Qe,et,tt,nt,ot,it,Jt,Ht],Je=class extends ao{programHelp=this.RULE("programHelp",()=>{this.AT_LEAST_ONE(()=>{this.CONSUME(D,{LABEL:"commandName"})}),this.MANY1(()=>{this.CONSUME(z)}),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(et),this.MANY(()=>{this.SUBRULE(this.sectionRow)})});commandsSection=this.RULE("commandsSection",()=>{this.CONSUME(tt),this.MANY1(()=>{this.SUBRULE1(this.sectionRow)})});optionsSection=this.RULE("optionsSection",()=>{this.CONSUME(Qe),this.MANY2(()=>{this.SUBRULE2(this.sectionRow)})});sectionRow=this.RULE("sectionRow",()=>{this.CONSUME(nt),this.OPTION(()=>{this.CONSUME(D,{LABEL:"parentCommandName"})}),this.MANY(()=>{this.CONSUME1(D,{LABEL:"commandName"})}),this.MANY1(()=>{this.OR([{ALT:()=>this.CONSUME(z)},{ALT:()=>this.CONSUME(ze)},{ALT:()=>this.CONSUME(qe)},{ALT:()=>this.CONSUME(ot,{LABEL:"description"})},{ALT:()=>this.CONSUME(it,{LABEL:"description"})},{ALT:()=>this.CONSUME(Ge)},{ALT:()=>this.CONSUME(We)},{ALT:()=>this.CONSUME(Ye)},{ALT:()=>this.CONSUME(Ke)},{ALT:()=>this.CONSUME(Ze)}])})});constructor(){super(mo),this.performSelfAnalysis()}},q=new Je,He=class extends q.getBaseCstVisitorConstructor(){constructor(){super(),this.validateVisitor()}programHelp(e){let{command:n,subcommand:i}=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:i}}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:i,...o}=e;return i===void 0?e:{arguments:[i,...n??[]],...o}}getString(e,n=!1){if(e!==void 0)return e.map(i=>n?this.clean(i.image):i.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(", ")}},co=new He;function qt(t){let e=so.tokenize(t);if(e.errors.length>0)throw new Error(`Errors lexing CLI command: ${JSON.stringify(e.errors,void 0,2)}`);q.input=e.tokens;let n=q.programHelp();if(q.errors.length>0)throw new Error(`Errors parsing CLI command help text: ${JSON.stringify(q.errors,void 0,2)}`);let i;try{i=co.visit(n)}catch(o){if(o instanceof Error)throw new TypeError(`Errors visiting CLI command help text: ${String(o)}`)}if(i===void 0)throw new Error("Could not parse help string");return i}var zt={meow:Ft,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 rt}from"remark-mdat";function Gt(t){for(let[e,n]of Object.entries(zt)){rt.info(`Trying to parse help string with ${e} parser...`);try{return n(t)}catch(i){i instanceof Error&&rt.info(`Error in "${e}" parser: ${String(i)}`);continue}}rt.error("Could not parse help string with any parser")}import{execaCommand as po}from"execa";import{log as Kt}from"remark-mdat";async function at(t,e="--help",n){let i=`${t} ${e}`,o=await fo(i),r=Gt(o);return r===void 0?(Kt.warn("Falling back to basic cli help text output."),uo(o)):lo(t,e,n??Number.MAX_SAFE_INTEGER,r)}async function lo(t,e,n,i){if(n<=0)return Kt.info("Max CLI command help depth reached, stopping recursion"),"";let o=$t(i,n),r=t.split(" ")[0];if(i.commands)for(let a of i.commands){if(!a.parentCommandName||!a.commandName)continue;let s=await at(`${r} ${a.commandName}`,e,n-1);if(s==="")return o;o+=`
|
|
14
15
|
|
|
15
16
|
${s}`}return o}function uo(t){return`\`\`\`txt
|
|
16
17
|
${t}
|
|
17
18
|
\`\`\``}async function fo(t){let e;try{let{stderr:n,stdout:i}=await po(t);e=i,(e===void 0||e==="")&&(e=n)}catch(n){if(n instanceof Error)throw new TypeError(`Error running CLI help command: "${t}"
|
|
18
19
|
${n.message}
|
|
19
20
|
`)}if(e===void 0||e==="")throw new Error(`No result from running CLI help command: "${t}"
|
|
20
|
-
`);return e}import{isExecutable as go}from"is-executable";import ho from"node:path";import{log as yo}from"remark-mdat";import wo from"which";async function
|
|
21
|
+
`);return e}import{isExecutable as go}from"is-executable";import ho from"node:path";import{log as yo}from"remark-mdat";import wo from"which";async function Wt(t){return t??=await bo(),Po(t)}async function bo(){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(Co(e))return yo.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 Co(t){let e=ho.parse(t);return e.root!==""||e.dir!==""}async function Po(t){let e=await wo(t,{nothrow:!0});if(e===null&&(e=await Oo(t)??void 0),e!==void 0&&await go(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 Yt={"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 Wt(e==null?void 0:e.cliCommand);return at(n,e==null?void 0:e.helpFlag,e==null?void 0:e.depth)}}};import Ro from"node:fs/promises";import Zt from"node:path";import{z as st}from"zod";var Xt={code:{async content(t){let e=st.object({file:st.string(),language:st.string().optional()}).parse(t),n=Zt.extname(e.file)??"",i=await Ro.readFile(Zt.join(process.cwd(),e.file),"utf8");return`\`\`\`${n}
|
|
21
22
|
${i}
|
|
22
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
|
|
23
24
|
[Issues](${e}) and pull requests are welcome.`},order:15,required:!0}};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
|
|
24
|
-
[${n}](license.txt) \xA9 ${e.name}`},order:16,required:!0}};import{getSoleRule as
|
|
25
|
+
[${n}](license.txt) \xA9 ${e.name}`},order:16,required:!0}};import{getSoleRule as Qt}from"remark-mdat";var en={footer:{content:[Qt(pe),Qt(le)],order:17}};var ue={"short-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,required:!0}};import{z as fe}from"zod";var ge={title:{applicationOrder:2,async content(t){let{postfix:e,prefix:n,titleCase:i}=fe.object({postfix:fe.string().optional().default(""),prefix:fe.string().optional().default(""),titleCase:fe.boolean().optional().default(!1)}).parse(t??{}),{name:o}=await h();return`# ${n}${i?So(o):o}${e}`},order:1,required:!0}};function So(t){return t.split(/[ _-]/).map(e=>e.charAt(0).toUpperCase()+e.slice(1)).join(" ")}import{getSoleRule as he}from"remark-mdat";var tn={header:{applicationOrder:2,content:[he(ge),he(ae),he(ie),he(ue)],order:1}};import{toc as ko}from"mdast-util-toc";import{remark as xo}from"remark";import Eo from"remark-gfm";import{z as k}from"zod";var ye={"table-of-contents":{applicationOrder:1,async content(t,e){let n=k.object({depth:k.union([k.literal(1),k.literal(2),k.literal(3),k.literal(4),k.literal(5),k.literal(6)]).optional()}).optional().parse(t),i=ko(e,{heading:null,maxDepth:(n==null?void 0:n.depth)??3,tight:!0}),o="## Table of contents";if(i.map===void 0)throw new Error("Could not generate table of contents");let r={children:i.map.children,type:"root"},a=xo().use(Eo).stringify(r).replaceAll(`
|
|
25
26
|
|
|
26
27
|
`,`
|
|
27
28
|
`);return[o,a].join(`
|
|
28
|
-
`)},order:6}};import{tldrawToImage as
|
|
29
|
+
`)},order:6}};import{tldrawToImage as nn}from"@kitschpatrol/tldraw-cli";import Lo from"node:crypto";import j from"node:fs/promises";import C from"node:path";import{isFile as mt}from"path-type";import{z as dt}from"zod";var sn={tldraw:{async content(t){let{alt:e="tldraw diagram",src:n}=dt.object({alt:dt.string().optional(),src:dt.string()}).parse(t),{assetsPath:i}=await P();if(i===void 0)throw new Error("No assets path found");await j.mkdir(i,{recursive:!0});let o=await mt(n)?await rn(n):void 0;if(o!==void 0){let m=C.basename(n,C.extname(n)),c=C.join(i,`${m}-${o}-light.svg`),p=C.join(i,`${m}-${o}-dark.svg`);if(await mt(c)&&await mt(p))return on(c,p,e)}let[r]=await nn(n,{dark:!1,format:"svg",output:i,transparent:!0});o??=await rn(r);let a=`${an(r)}-${o}-light.svg`;await j.rename(r,a);let[s]=await nn(n,{dark:!0,format:"svg",output:i,transparent:!0}),d=`${an(s)}-${o}-dark.svg`;if(await j.rename(s,d),o!==void 0){let m=C.basename(d),c=C.basename(a),p=c.replace(`${o}-light.svg`,""),g=await j.readdir(i);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(i,w))}}return on(a,d,e)}}};async function on(t,e,n){let{packageFile:i}=await P();if(i===void 0)throw new Error("No package file found");let o=C.dirname(i),r=C.relative(o,t);return`<picture>
|
|
29
30
|
<source media="(prefers-color-scheme: dark)" srcset="${C.relative(o,e)}">
|
|
30
31
|
<source media="(prefers-color-scheme: light)" srcset="${r}">
|
|
31
32
|
<img alt="${n}" src="${r}">
|
|
32
|
-
</picture>`}async function
|
|
33
|
+
</picture>`}async function rn(t){let e=await j.readFile(t),n=Lo.createHash("sha1");return n.update(e),n.digest("hex").slice(0,8)}function an(t){return t.replace(/\.[^./]+$/,"")}import{getSoleRule as vo}from"remark-mdat";var mn={toc:{applicationOrder:1,content:[vo(ye)]}};var dn={...ie,...ae,...Yt,...Xt,...pe,...en,...tn,...le,...ue,...ye,...sn,...mn,...ge};async function we(t){let e={addMetaComment:!0,rules:dn},{additionalConfig:n=[],...i}=t??{},o=Array.isArray(n)?n:[n],r=await L({additionalConfig:[e,...o],...i});if(r.packageFile===void 0)throw new Error("Package file path is required in `mdat readme` config");return r}import{findUp as To}from"find-up";import{packageDirectory as $o}from"pkg-dir";import{log as cn}from"remark-mdat";async function ct(){cn.info("Searching for package directory...");let t=await $o()??process.cwd(),e=await To("readme.md",{stopAt:t,type:"file"});if(e!==void 0)return cn.info(`Found closest readme at "${e}"`),e}async function be(){let t=await ct();if(t===void 0)throw new Error("No readme found");return t}async function Ce(t,e,n,i,o){return t??=await be(),S(t,we,te,e,n,i,o)}async function pn(t,e,n,i,o){return t??=await be(),S(t,we,oe,e,n,i,o)}async function ln(t,e,n,i,o){return t??=await be(),S(t,we,ne,e,n,i,o)}var un=`<!-- header -->
|
|
33
34
|
|
|
34
35
|
<!-- table-of-contents -->
|
|
35
36
|
|
|
@@ -299,4 +300,4 @@ _State anyone or anything that significantly helped with the development of your
|
|
|
299
300
|
<!-- contributing -->
|
|
300
301
|
|
|
301
302
|
<!-- license -->
|
|
302
|
-
`;var T={"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 k from"chalk";import Vo from"node:fs/promises";import Ce from"node:path";import{deepMergeDefined as Bo}from"remark-mdat";import{write as Jo}from"to-vfile";async function Pn(){let t=await dt(),e=await X();return{packageDirectory:e===void 0?void 0:Ce.dirname(Ce.resolve(e)),readmePath:t}}async function On(){let{packageDirectory:t,readmePath:e}=await Pn(),n=Ce.resolve(process.cwd());Fo(`Running ${k.bold("mdat readme init")} interactively`);let i=await jo({overwrite:async()=>e===void 0||await bn({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?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: "${k.blue(t)}"`,value:t},{label:`Create in current working directory: "${k.blue(n)}"`,value:n}]}):n,template:async()=>pt({message:"Which template would you like to use?",options:qo()}),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 ${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: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")}}),o=await lt(i);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: "${k.bold.blue(o)}"`),Uo("Done!"),o}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(T)[0]},t??{}),i=Ho(n.template,n.compound),o=Ce.join(n.output,"readme.md");await Vo.writeFile(o,i,"utf8");let r=await cn(void 0,void 0,{readmeFile:o});return await Jo(r),o}function Ho(t,e){let i=T[t].content[e?"compound":"explicit"];if(i===void 0||i==="")throw new Error(`No template found for "${t}"`);return i}function qo(){return Object.entries(T).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 configs.",string:!0,type:"array"}},G={meta:{alias:"m",description:"Embed an extra comment at the top of the generated Markdown noting the date of generation and 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"}},j={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"}},Pe=["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}},xn={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"}},Rn={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"}},Sn={expand:{alias:"e",default:!0,description:"Automatically run `mdat readme` immediately after creating the readme template.",type:"boolean"}},kn={template:{alias:"t",choices:Object.keys(T),default:Object.keys(T)[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"}},Oe=["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 A from"pretty-ms";import{getMdatReports as zo,log as u,reporterMdat as F}from"remark-mdat";import{write as xe}from"to-vfile";import Go from"yargs";import{hideBin as Ko}from"yargs/helpers";var _=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(...Pe).option($).option(Y).option(j).option(K).option(G).option(N).option(W).option(E),async({config:t,files:e,meta:n,name:i,output:o,prefix:r,print:a,rules:s,verbose:d})=>{u.verbose=d??!1,Re({name:i,output:o,print:a});let m=U(t,{addMetaComment:n,keywordPrefix:r}),c=await Et(e,i,o,m,s);for(let p of c)a?process.stdout.write(p.toString()):await xe(p);F(c),u.info(`Expanded comments in ${A(performance.now()-_)}.`),process.exitCode=V(c)}).command("check <files..> [options]","Validate a markdown file with `mdat` placeholder comments.",t=>t.positional(...Pe).option($).option(Y).option(G).option(N).option(E),async({config:t,files:e,meta:n,prefix:i,rules:o,verbose:r})=>{u.verbose=r??!1;let a=U(t,{addMetaComment:n,keywordPrefix:i}),s=await Lt(e,void 0,void 0,a,o);F(s),u.info(`Checked comments in ${A(performance.now()-_)}.`),process.exitCode=V(s)}).command("collapse <files..> [options]","Collapse `mdat` placeholder comments.",t=>t.positional(...Pe).option($).option(j).option(K).option(N).option(W).option(E),async({config:t,files:e,name:n,output:i,prefix:o,print:r,verbose:a})=>{u.verbose=a??!1,Re({name:n,output:i,print:r});let s=U(t,{keywordPrefix:o}),d=await vt(e,void 0,void 0,s);for(let m of d)r?process.stdout.write(m.toString()):await xe(m);F(d),u.info(`Cleaned comments in ${A(performance.now()-_)}.`),process.exitCode=V(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(...Oe).option($).option(Y).option(j).option(K).option(ut).option(ft).option(N).option(G).option(W).option(E),async({assets:e,config:n,files:i,meta:o,name:r,output:a,package:s,prefix:d,print:m,rules:c,verbose:p})=>{u.verbose=p??!1,Re({name:r,output:a,print:m});let g=U(n,{addMetaComment:o,assetsPath:e,keywordPrefix:d,packageFile:s}),y=await ct(i,r,a,g,c);for(let I of y)m?process.stdout.write(I.toString()):await xe(I);F(y);let{packageFile:w}=await P();u.info(`Pulled package metadata from: ${gt.bold.blue(w)}`),u.info(`Expanded readme(s) in ${A(performance.now()-_)}.`),process.exitCode=V(y)}).command("check [files..] [options]","Validate `mdat` placeholder comments in your readme.md.",e=>e.positional(...Oe).option($).option(Y).option(ut).option(ft).option(N).option(G).option(E),async({assets:e,config:n,files:i,meta:o,package:r,prefix:a,rules:s,verbose:d})=>{u.verbose=d??!1;let m=U(n,{addMetaComment:o,assetsPath:e,keywordPrefix:a,packageFile:r}),c=await pn(i,void 0,void 0,m,s);F(c);let{packageFile:p}=await P();u.info(`Pulled package metadata from: ${gt.bold.blue(p)}`),u.info(`Checked readme(s) in ${A(performance.now()-_)}.`),process.exitCode=V(c)}).command("collapse [files..] [options]","Collapse `mdat` placeholder comments in your readme.md.",e=>e.positional(...Oe).option(j).option(K).option(W).option($).option(N).option(E),async({config:e,files:n,name:i,output:o,prefix:r,print:a,verbose:s})=>{u.verbose=s??!1,Re({name:i,output:o,print:a});let d=U(e,{keywordPrefix:r}),m=await ln(n,void 0,void 0,d);for(let c of m)a?process.stdout.write(c.toString()):await xe(c);F(m),u.info(`Cleaned readme(s) in ${A(performance.now()-_)}.`),process.exitCode=V(m)}).command("init [options]","Interactively create a new readme.md file with sensible default `mdat` comment placeholders.",e=>e.option(xn).option(Rn).option(j).option(Sn).option(kn).option(En).option(E),async({compound:e,expand:n,interactive:i,output:o,overwrite:r,template:a,verbose:s})=>{if(u.verbose=s??!1,i)await On();else{let d=await lt({compound:e,expand:n,output:o,overwrite:r,template:a});u.info(`Created readme at "${gt.blue(d)}" in ${A(performance.now()-_)}.`)}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 Re(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 U(t,e){return[...Q(t),e]}function V(t){return zo(t).reduce((i,o)=>i+o.errors.length,0)>0?1:0}
|
|
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 i=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:qo()}),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")}}),o=await lt(i);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(o)}"`),Uo("Done!"),o}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??{}),i=Ho(n.template,n.compound),o=Pe.join(n.output,"readme.md");await Vo.writeFile(o,i,"utf8");let[r]=await Ce(o);return await Jo(r),o}function Ho(t,e){let i=$[t].content[e?"compound":"explicit"];if(i===void 0||i==="")throw new Error(`No template found for "${t}"`);return i}function qo(){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 noting the date of generation and 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 zo,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:i,output:o,prefix:r,print:a,rules:s,verbose:d})=>{u.verbose=d??!1,ke({name:i,output:o,print:a});let m=V(t,{addMetaComment:n,keywordPrefix:r}),c=await Et(e,i,o,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:i,rules:o,verbose:r})=>{u.verbose=r??!1;let a=V(t,{addMetaComment:n,keywordPrefix:i}),s=await Lt(e,void 0,void 0,a,o);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:i,prefix:o,print:r,verbose:a})=>{u.verbose=a??!1,ke({name:n,output:i,print:r});let s=V(t,{keywordPrefix:o}),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:i,meta:o,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:o,assetsPath:e,keywordPrefix:d,packageFile:s}),y=await Ce(i,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:i,meta:o,package:r,prefix:a,rules:s,verbose:d})=>{u.verbose=d??!1;let m=V(n,{addMetaComment:o,assetsPath:e,keywordPrefix:a,packageFile:r}),c=await pn(i,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:i,output:o,prefix:r,print:a,verbose:s})=>{u.verbose=s??!1,ke({name:i,output:o,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:i,output:o,overwrite:r,template:a,verbose:s})=>{if(u.verbose=s??!1,i)await On();else{let d=await lt({compound:e,expand:n,output:o,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 zo(t).reduce((i,o)=>i+o.errors.length,0)>0?1:0}
|
package/dist/index.js
CHANGED
|
@@ -1,31 +1,32 @@
|
|
|
1
|
-
import{defaultLoaders as
|
|
1
|
+
import{defaultLoaders as Ft}from"cosmiconfig";function re(t,e){let n=Ft[".json"],r=n(t,e);return Ve(r)}function Ve(t,e="",n={}){for(let[r,o]of Object.entries(t)){let i=e?`${e}.${r}`:r;typeof o=="object"&&o!==null&&!Array.isArray(o)?Ve(o,i,n):o===null?n[i]="null":n[i]=o.toString()}return n}import jt from"node:fs";import P from"node:path";import{packageUp as Dt}from"package-up";import{isFileSync as Je}from"path-type";import Ut from"untildify";function vt(t,e){let n=e===0?1:Math.floor(Math.log10(Math.abs(e))+1);return t.toString().padStart(n,"0")}function He(t,e,n,r){let o=[];for(let[i,s]of t.entries()){let a=n&&t.length>1?`-${vt(i+1,t.length+1)}`:"",d=It(s,e,n,r,a);o.push(d)}return o}function It(t,e,n,r,o=""){let i=Be(t),s=e?Be(e):void 0;if(!Je(i))throw new Error(`Input file not found: "${i}"`);if(s){if(Je(s))throw new Error(`Output path must be a directory, received a file path: "${s}"`);jt.mkdirSync(s,{recursive:!0})}let a=n?P.basename(n,P.extname(n)):P.basename(i,P.extname(i)),d=`.${r??(n&&P.extname(n)!==""?P.extname(n):P.extname(t)===""?"":P.extname(t))}`,m=`${a}${o}${d}`,p=s??P.dirname(i);return{input:i,name:m,output:p}}function Be(t){return Ut(t)}async function ze(){return Dt()}function qe(t){return t==null?[]:Array.isArray(t)?t:[t]}import Ke from"chalk";import{cosmiconfig as Ge}from"cosmiconfig";import _t from"node:fs/promises";import Ze from"node:path";import Vt from"plur";import{readPackage as Jt}from"read-pkg";import{deepMergeDefined as _,log as h,optionsSchema as Bt,rulesSchema as Ht}from"remark-mdat";import{z as ie}from"zod";var Ye=Bt.merge(ie.object({assetsPath:ie.string().optional(),packageFile:ie.string().optional()})).describe("Config Extension");async function y(t){let{additionalConfig:e,additionalRules:n,searchFrom:r}=t??{},o={addMetaComment:!1,assetsPath:"./assets",closingPrefix:"/",keywordPrefix:"",metaCommentIdentifier:"+",packageFile:await ze(),rules:{mdat:"Powered by the Markdown Autophagic Template system: [mdat](https://github.com/kitschpatrol/mdat)."}},i=Ge("mdat"),s=await i.search(r);if(s){let{config:a,filepath:d}=s;h.info(`Using config from "${d}"`);let m=We(a,Ye);m&&(o=_(o,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=We(m,Ye);p!==void 0&&(o=_(o,p))}}if(n!==void 0){let a=Array.isArray(n)?n:[n],d=Ge("mdat",{loaders:{".json":re}});for(let m of a){let p;if(typeof m=="string"){let g;if(Ze.basename(m).endsWith("package.json")){let oe=await _t.readFile(m,"utf8");g={config:re(m,oe),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=zt(p,Ht);f!==void 0&&(o=_(o,f))}}if(o.rules){let a=Object.keys(o.rules).sort().map(d=>`"${Ke.bold.green(d)}"`);h.info(`Loaded ${Ke.bold(a.length)} mdat comment expansion ${Vt("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=o,o}function zt(t,e){if(e.safeParse(t).success)return{rules:t};h.error(`Rules object has the wrong shape. Ignoring and using default configuration:
|
|
2
2
|
${JSON.stringify(t,void 0,2)}`)}function We(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 se;async function l(){let{packageFile:t}=await b();if(t===void 0)throw new Error("No packageFile found or set in config");if(se??=await
|
|
4
|
-
`)},order:3,required:!1}};import{globby as
|
|
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 se;async function l(){let{packageFile:t}=await b();if(t===void 0)throw new Error("No packageFile found or set in config");if(se??=await Jt({cwd:Ze.dirname(t)}),se===void 0)throw new Error("No package.json found");return se}function qt(t,e){return _(t,e)}import{remark as ae}from"remark";import me from"remark-gfm";import{mdatCheck as Kt,mdatClean as Xe,mdatExpand as Gt,mdatSplit as Qe}from"remark-mdat";import{read as Yt}from"to-vfile";import{VFile as Wt}from"vfile";async function E(t,e,n,r,o,i,s){let a=await e({additionalConfig:i,additionalRules:s});i=a;let d=qe(t),m=He(d,o,r,"md"),p=[],f=n(a);for(let{input:g,name:L,output:w}of m){let oe=await Yt(g),I=await f.process(oe);I.dirname=w,I.basename=L,p.push(I)}return p}async function O(t,e,n,r,o){let i=await e({additionalConfig:r,additionalRules:o});return r=i,n(i).process(new Wt(t))}function $(t){return ae().use({settings:{bullet:"-",emphasis:"_"}}).use(me).use(()=>async function(n,r){Qe(n,r),Xe(n,r,t),await Gt(n,r,t)})}function F(t){return ae().use({settings:{bullet:"-",emphasis:"_"}}).use(me).use(()=>function(n,r){Qe(n,r),Xe(n,r,t)})}function x(t){return ae().use({settings:{bullet:"-",emphasis:"_"}}).use(me).use(()=>async function(n,r){await Kt(n,r,{...t,paranoid:!1})})}async function Zt(t,e,n,r,o){return E(t,y,$,e,n,r,o)}async function Xt(t,e,n){return O(t,y,$,e,n)}async function Qt(t,e,n,r,o){return E(t,y,x,e,n,r,o)}async function en(t,e,n){return O(t,y,x,e,n)}async function tn(t,e,n,r,o){return E(t,y,F,e,n,r,o)}async function nn(t,e,n){return O(t,y,F,e,n)}import{z as k}from"zod";var J={badges:{async content(t){var s;let e=k.object({custom:k.record(k.object({image:k.string(),link:k.string()})).optional(),npm:k.array(k.string()).optional()}).optional().parse(t),n=await l(),{name:r}=n,o=[];if(!n.private&&((s=n.publishConfig)==null?void 0:s.access)==="public"&&o.push(`[](https://npmjs.com/package/${r})`),(e==null?void 0:e.npm)!==void 0)for(let a of e.npm)o.push(`[](https://npmjs.com/package/${a})`);let{license:i}=n;if(i!==void 0&&o.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))o.push(`[](${m})`);return o.join(`
|
|
4
|
+
`)},order:3,required:!1}};import{globby as on}from"globby";import B from"node:path";import{isFile as rn}from"path-type";import{readPackage as sn}from"read-pkg";import{z as de}from"zod";var H={banner:{async content(t){let e=de.object({alt:de.string().optional(),src:de.string().optional()}).optional().parse(t),{assetsPath:n,packageFile:r}=await b();if(r===void 0)throw new Error("No package.json found");let o=(e==null?void 0:e.src)??await an(n);if(o===void 0)throw new Error("Banner image not found at any typical location, consider adding something at ./assets/banner.webp");if(!et(o)&&!await rn(o))throw new Error(`Banner image not found at "${o}"`);let i=(e==null?void 0:e.alt)??`${(await sn({cwd:B.dirname(r)})).name} banner`;if(i===void 0||i==="undefined banner")throw new Error("Banner image alt text not available");return``},order:2}};async function an(t){let{packageFile:e}=await b();if(e===void 0)throw new Error("No package.json found");let n=B.dirname(e),r=t===void 0?[".","assets","media","readme-assets","readme-media","readme","images"]:[t],o=["banner","header","logo","readme","cover","screenshot","screenshots","demo","overview","image","hero"],i=["png","gif","jpg","jpeg","svg","webp"],s=await on(r.map(a=>B.join(n,a)),{expandDirectories:{extensions:i,files:o}});if(s.length>0)return B.relative(process.cwd(),s[0])}function et(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?et(`https://${t}`,!1):!1}}function tt(t,e=Number.MAX_SAFE_INTEGER){let n=[],r=mn(t,e);return n.push(dn(r)),n.push(cn(t,r)),r.hasMultipleSubcommands&&r.canRecurse&&n.push(pn(r.fullCommandName)),r.defaultCommand&&n.push(fn(r)),n.push(un(t,r)),t.positionals&&!r.commandsOnly&&n.push(ce(["Positional Argument","Description","Type","Default"],t.positionals.map(o=>[o.arguments?[o.arguments.map(i=>`\`${i}\``)].join(" "):"",`${o.description??""}${o.required?" _(Required.)_":" _(Optional.)_"}`,o.type?`\`${o.type}\``:"",o.defaultValue?o.defaultValue.includes(" ")?o.defaultValue:`\`${o.defaultValue}\``:""]))),t.commands&&n.push(ce(["Command","Argument","Description"],t.commands.map(o=>{var i;return[`\`${o.commandName??(o.default?"[default]":"")}\``,o.arguments?(i=o.arguments)==null?void 0:i.map(s=>`\`${s}\``).join(" "):"",`${o.description??""}${o.default?" _(Default command.)_":""}`]}))),t.options&&!r.commandsOnly&&n.push(ce(["Option","Alias","Argument","Description","Type","Default"],t.options.map(o=>[o.flags?o.flags.map(i=>`\`${i}\``).join(" "):"",o.aliases?o.aliases.map(i=>`\`${i}\``).join(" "):"",o.arguments?o.arguments.map(i=>`\`${i}\``).join(" "):"",o.description??"",o.type?`\`${o.type}\``:"",o.defaultValue?o.defaultValue.includes(" ")?o.defaultValue:`\`${o.defaultValue}\``:""]))),r.commandsOnly&&n.push("_See the sections below for more information on each subcommand._"),n.join(`
|
|
5
|
+
|
|
6
|
+
`)}function mn(t,e){var m,p;let n=t.subcommandName===void 0,r=t.commands?t.commands.length>1:!1,o=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}`:""}`;return{canRecurse:o,commandsOnly:o&&r,defaultCommand:i,fullCommandName:a,hasMultipleSubcommands:r,isTopLevel:n,topLevelCommand:s}}function dn(t){return`#### ${t.isTopLevel?"Command":"Subcommand"}: \`${t.fullCommandName}\``}function cn(t,e){var n,r;return e.isTopLevel&&((n=e.topLevelCommand)!=null&&n.description)?(t.commands=(r=t.commands)==null?void 0:r.filter(o=>o!==e.topLevelCommand),e.topLevelCommand.description):t.description??""}function pn(t){return`This section lists top-level commands for \`${t}\`.`}function fn(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 un(t,e){var r;let n=(r=e.topLevelCommand)!=null&&r.arguments?` ${e.topLevelCommand.arguments.join(" ")}`:`${t.arguments?` ${t.arguments.join(" ")}`:""}`;return`Usage:
|
|
5
7
|
|
|
6
|
-
`)}function an(t,e){var a,p;let n=t.subcommandName===void 0,r=t.commands?t.commands.length>1:!1,o=e>1,i=(a=t.commands)==null?void 0:a.find(f=>f.default),s=(p=t.commands)==null?void 0:p.find(f=>f.commandName===void 0),m=`${t.commandName}${t.subcommandName?` ${t.subcommandName}`:""}`;return{canRecurse:o,commandsOnly:o&&r,defaultCommand:i,fullCommandName:m,hasMultipleSubcommands:r,isTopLevel:n,topLevelCommand:s}}function mn(t){return`#### ${t.isTopLevel?"Command":"Subcommand"}: \`${t.fullCommandName}\``}function dn(t,e){var n,r;return e.isTopLevel&&((n=e.topLevelCommand)!=null&&n.description)?(t.commands=(r=t.commands)==null?void 0:r.filter(o=>o!==e.topLevelCommand),e.topLevelCommand.description):t.description??""}function cn(t){return`This section lists top-level commands for \`${t}\`.`}function pn(t){var e;return`If no command is provided, \`${t.fullCommandName} ${(e=t.defaultCommand)==null?void 0:e.commandName}\` is run by default.`}function fn(t,e){var r;let n=(r=e.topLevelCommand)!=null&&r.arguments?` ${e.topLevelCommand.arguments.join(" ")}`:`${t.arguments?` ${t.arguments.join(" ")}`:""}`;return`Usage:
|
|
7
8
|
\`\`\`txt
|
|
8
9
|
${e.fullCommandName}${n}
|
|
9
|
-
\`\`\``}function ce(t,e){let n=
|
|
10
|
+
\`\`\``}function ce(t,e){let n=ln(e);t=t.filter((o,i)=>!n.includes(i)),e=e.map(o=>o.filter((i,s)=>!n.includes(s)));let r="";r+=`| ${t.join(" | ")} |
|
|
10
11
|
`,r+=`| ${t.map(()=>"---").join(" | ")} |
|
|
11
12
|
`;for(let o of e)r+=`| ${o.join(" | ")} |
|
|
12
|
-
`;return r}function
|
|
13
|
+
`;return r}function ln(t){var r;let e=[],n=((r=t[0])==null?void 0:r.length)||0;for(let o=0;o<n;o++){let i=!0;for(let s of t)if(s[o]!==""){i=!1;break}i&&e.push(o)}return e}import{CstParser as gn,Lexer as S,createToken as u}from"chevrotain";var q=u({name:"flag",pattern:/--[\w-_]+/}),ue=u({longer_alt:q,name:"alias",pattern:/-[A-Za-z]/}),nt=u({group:S.SKIPPED,name:"comma",pattern:/,/}),ot=u({group:S.SKIPPED,name:"dollar",pattern:/\$/}),z=u({group:S.SKIPPED,name:"whiteSpace",pattern:/ /}),rt=u({group:S.SKIPPED,name:"newLine",pattern:/\n/}),le=u({name:"word",pattern:/\S+/}),D=u({name:"argument",pattern:/(<\S+>|\[.+])/}),ge=u({name:"programDescription",pattern:/\w.+(?=\n\n {2}Usage)/}),it=u({group:S.SKIPPED,name:"startUsage",pattern:/ {2}Usage\n/,push_mode:"USAGE_MODE"}),st=u({group:S.SKIPPED,name:"endUsage",pattern:/\n/,pop_mode:!0}),he=u({name:"startOptions",pattern:/ {2}Options\n/,push_mode:"OPTIONS_MODE"}),ye=u({name:"startRow",pattern:/ {4}/,push_mode:"ROW_MODE"}),Ce=u({name:"rowDescription",pattern:/\w.+/}),at=u({group:S.SKIPPED,name:"endRow",pattern:/\n/,pop_mode:!0}),mt=u({group:S.SKIPPED,name:"endOptions",pattern:/\n/,pop_mode:!0}),hn=new S({defaultMode:"DEFAULT_MODE",modes:{DEFAULT_MODE:[it,he,ge,rt,z],OPTIONS_MODE:[mt,ye],ROW_MODE:[at,ue,q,nt,D,Ce,z],USAGE_MODE:[st,ot,D,le,z]}}),yn=[q,ue,nt,ot,z,rt,le,D,ge,it,st,he,ye,Ce,at,mt],pe=class extends gn{programHelp=this.RULE("programHelp",()=>{this.CONSUME(ge,{LABEL:"description"}),this.AT_LEAST_ONE(()=>{this.CONSUME(le,{LABEL:"commandName"})}),this.MANY(()=>{this.CONSUME(D)}),this.OPTION(()=>{this.SUBRULE(this.optionsSection)})});optionsSection=this.RULE("optionsSection",()=>{this.CONSUME(he),this.MANY(()=>{this.SUBRULE(this.sectionRow)})});sectionRow=this.RULE("sectionRow",()=>{this.CONSUME(ye),this.MANY(()=>{this.OR([{ALT:()=>this.CONSUME(D)},{ALT:()=>this.CONSUME(ue)},{ALT:()=>this.CONSUME(q)},{ALT:()=>this.CONSUME(Ce,{LABEL:"description"})}])})});constructor(){super(yn),this.performSelfAnalysis()}},j=new pe,fe=class extends j.getBaseCstVisitorConstructor(){constructor(){super(),this.validateVisitor()}programHelp(e){let{command:n,subcommand:r}=K(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:r}}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(r=>n?this.clean(r.image):r.image).join(" ")}getArray(e){if(e!==void 0)return e.map(n=>n.image)}clean(e){return e.replaceAll(/^[\s[]*(default:)?\s*|[\s\]]*$/g,"")}},Cn=new fe;function dt(t){let e=hn.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 r;try{r=Cn.visit(n)}catch(o){if(o instanceof Error)throw new TypeError(`Errors visiting CLI command help text: ${String(o)}`)}if(r===void 0)throw new Error("Could not parse help string");return r}import{CstParser as wn,Lexer as N,createToken as c}from"chevrotain";var Ee=c({name:"flag",pattern:/--[\w-_]+/}),Re=c({name:"alias",pattern:/-[A-Za-z]/}),ct=c({group:N.SKIPPED,name:"comma",pattern:/,/}),A=c({name:"word",pattern:/\S+/}),v=c({name:"argument",pattern:/<\S+>|\[\S+]/}),Le=c({name:"type",pattern:/\[(boolean|string|array)]/}),be=c({name:"defaultInfo",pattern:/\[default]/}),Oe=c({name:"required",pattern:/\[required]/}),ke=c({name:"defaultInfoDescription",pattern:/\[default:\s.+?]/}),Ne=c({name:"choices",pattern:/\[choices:\s.+?]/}),we=c({group:N.SKIPPED,name:"whiteSpace",pattern:/\s/}),pt=c({group:N.SKIPPED,name:"startProgramDescription",pattern:/\n\n/,push_mode:"PROGRAM_DESCRIPTION_MODE"}),Te=c({name:"programDescription",pattern:/.+/}),ft=c({group:N.SKIPPED,name:"endProgramDescription",pattern:/\n\n/,pop_mode:!0}),$e=c({name:"startOptionsSection",pattern:/Options:?\n/,push_mode:"SECTION_MODE"}),xe=c({name:"startPositionalsSection",pattern:/Positionals:\n/,push_mode:"SECTION_MODE"}),Ae=c({name:"startCommandsSection",pattern:/Commands:\n/,push_mode:"SECTION_MODE"}),Me=c({name:"startRow",pattern:/ {2,}/,push_mode:"ROW_MODE"}),Fe=c({name:"rowDescription",pattern:/ {2}\w.+ {2}/}),je=c({name:"rowDescriptionTerminal",pattern:/ {2}\w.+/}),ut=c({group:N.SKIPPED,name:"endRow",pattern:/\n/,pop_mode:!0}),lt=c({group:N.SKIPPED,name:"endSection",pattern:/\n+/,pop_mode:!0}),Pn=new N({defaultMode:"DEFAULT_MODE",modes:{DEFAULT_MODE:[$e,xe,Ae,pt,v,A,we],PROGRAM_DESCRIPTION_MODE:[ft,Te],ROW_MODE:[ut,ct,Le,Fe,je,ke,be,Oe,Ne,Ee,Re,v,A,we],SECTION_MODE:[Me,lt]}}),Sn=[Ee,Re,ct,A,v,Le,be,Oe,ke,Ne,we,pt,Te,ft,$e,xe,Ae,Me,Fe,je,ut,lt],Pe=class extends wn{programHelp=this.RULE("programHelp",()=>{this.AT_LEAST_ONE(()=>{this.CONSUME(A,{LABEL:"commandName"})}),this.MANY1(()=>{this.CONSUME(v)}),this.OPTION(()=>{this.CONSUME(Te,{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(xe),this.MANY(()=>{this.SUBRULE(this.sectionRow)})});commandsSection=this.RULE("commandsSection",()=>{this.CONSUME(Ae),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(Me),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(Re)},{ALT:()=>this.CONSUME(Ee)},{ALT:()=>this.CONSUME(Fe,{LABEL:"description"})},{ALT:()=>this.CONSUME(je,{LABEL:"description"})},{ALT:()=>this.CONSUME(Le)},{ALT:()=>this.CONSUME(Oe)},{ALT:()=>this.CONSUME(ke)},{ALT:()=>this.CONSUME(be)},{ALT:()=>this.CONSUME(Ne)}])})});constructor(){super(Sn),this.performSelfAnalysis()}},U=new Pe,Se=class extends U.getBaseCstVisitorConstructor(){constructor(){super(),this.validateVisitor()}programHelp(e){let{command:n,subcommand:r}=K(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:r}}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:r,...o}=e;return r===void 0?e:{arguments:[r,...n??[]],...o}}getString(e,n=!1){if(e!==void 0)return e.map(r=>n?this.clean(r.image):r.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(", ")}},En=new Se;function gt(t){let e=Pn.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 r;try{r=En.visit(n)}catch(o){if(o instanceof Error)throw new TypeError(`Errors visiting CLI command help text: ${String(o)}`)}if(r===void 0)throw new Error("Could not parse help string");return r}var ht={meow:dt,yargs:gt};function K(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 De}from"remark-mdat";function yt(t){for(let[e,n]of Object.entries(ht)){De.info(`Trying to parse help string with ${e} parser...`);try{return n(t)}catch(r){r instanceof Error&&De.info(`Error in "${e}" parser: ${String(r)}`);continue}}De.error("Could not parse help string with any parser")}import{execaCommand as Rn}from"execa";import{log as Ct}from"remark-mdat";async function Ue(t,e="--help",n){let r=`${t} ${e}`,o=await On(r),i=yt(o);return i===void 0?(Ct.warn("Falling back to basic cli help text output."),bn(o)):Ln(t,e,n??Number.MAX_SAFE_INTEGER,i)}async function Ln(t,e,n,r){if(n<=0)return Ct.info("Max CLI command help depth reached, stopping recursion"),"";let o=tt(r,n),i=t.split(" ")[0];if(r.commands)for(let s of r.commands){if(!s.parentCommandName||!s.commandName)continue;let a=await Ue(`${i} ${s.commandName}`,e,n-1);if(a==="")return o;o+=`
|
|
13
14
|
|
|
14
|
-
${
|
|
15
|
+
${a}`}return o}function bn(t){return`\`\`\`txt
|
|
15
16
|
${t}
|
|
16
|
-
\`\`\``}async function
|
|
17
|
+
\`\`\``}async function On(t){let e;try{let{stderr:n,stdout:r}=await Rn(t);e=r,(e===void 0||e==="")&&(e=n)}catch(n){if(n instanceof Error)throw new TypeError(`Error running CLI help command: "${t}"
|
|
17
18
|
${n.message}
|
|
18
19
|
`)}if(e===void 0||e==="")throw new Error(`No result from running CLI help command: "${t}"
|
|
19
|
-
`);return e}import{isExecutable as
|
|
20
|
+
`);return e}import{isExecutable as kn}from"is-executable";import Nn from"node:path";import{log as Tn}from"remark-mdat";import $n from"which";async function wt(t){return t??=await xn(),Mn(t)}async function xn(){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(An(e))return Tn.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 An(t){let e=Nn.parse(t);return e.root!==""||e.dir!==""}async function Mn(t){let e=await $n(t,{nothrow:!0});if(e===null&&(e=await Fn(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 Fn(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 G}from"zod";var Pt={"cli-help":{async content(t){let e=G.object({cliCommand:G.string().optional(),depth:G.number().optional(),helpFlag:G.string().optional()}).optional().parse(t),n=await wt(e==null?void 0:e.cliCommand);return Ue(n,e==null?void 0:e.helpFlag,e==null?void 0:e.depth)}}};import jn from"node:fs/promises";import St from"node:path";import{z as ve}from"zod";var Et={code:{async content(t){let e=ve.object({file:ve.string(),language:ve.string().optional()}).parse(t),n=St.extname(e.file)??"",r=await jn.readFile(St.join(process.cwd(),e.file),"utf8");return`\`\`\`${n}
|
|
20
21
|
${r}
|
|
21
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
|
|
22
23
|
[Issues](${e}) and pull requests are welcome.`},order:15,required:!0}};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
|
|
23
|
-
[${n}](license.txt) \xA9 ${e.name}`},order:16,required:!0}};import{getSoleRule as
|
|
24
|
+
[${n}](license.txt) \xA9 ${e.name}`},order:16,required:!0}};import{getSoleRule as Rt}from"remark-mdat";var Lt={footer:{content:[Rt(Y),Rt(W)],order:17}};var Z={"short-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,required:!0}};import{z as X}from"zod";var Q={title:{applicationOrder:2,async content(t){let{postfix:e,prefix:n,titleCase:r}=X.object({postfix:X.string().optional().default(""),prefix:X.string().optional().default(""),titleCase:X.boolean().optional().default(!1)}).parse(t??{}),{name:o}=await l();return`# ${n}${r?Dn(o):o}${e}`},order:1,required:!0}};function Dn(t){return t.split(/[ _-]/).map(e=>e.charAt(0).toUpperCase()+e.slice(1)).join(" ")}import{getSoleRule as ee}from"remark-mdat";var bt={header:{applicationOrder:2,content:[ee(Q),ee(H),ee(J),ee(Z)],order:1}};import{toc as Un}from"mdast-util-toc";import{remark as vn}from"remark";import In from"remark-gfm";import{z as R}from"zod";var te={"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),r=Un(e,{heading:null,maxDepth:(n==null?void 0:n.depth)??3,tight:!0}),o="## Table of contents";if(r.map===void 0)throw new Error("Could not generate table of contents");let i={children:r.map.children,type:"root"},s=vn().use(In).stringify(i).replaceAll(`
|
|
24
25
|
|
|
25
26
|
`,`
|
|
26
27
|
`);return[o,s].join(`
|
|
27
|
-
`)},order:6}};import{tldrawToImage as
|
|
28
|
+
`)},order:6}};import{tldrawToImage as Ot}from"@kitschpatrol/tldraw-cli";import _n from"node:crypto";import M from"node:fs/promises";import C from"node:path";import{isFile as Ie}from"path-type";import{z as _e}from"zod";var $t={tldraw:{async content(t){let{alt:e="tldraw diagram",src:n}=_e.object({alt:_e.string().optional(),src:_e.string()}).parse(t),{assetsPath:r}=await b();if(r===void 0)throw new Error("No assets path found");await M.mkdir(r,{recursive:!0});let o=await Ie(n)?await Nt(n):void 0;if(o!==void 0){let m=C.basename(n,C.extname(n)),p=C.join(r,`${m}-${o}-light.svg`),f=C.join(r,`${m}-${o}-dark.svg`);if(await Ie(p)&&await Ie(f))return kt(p,f,e)}let[i]=await Ot(n,{dark:!1,format:"svg",output:r,transparent:!0});o??=await Nt(i);let s=`${Tt(i)}-${o}-light.svg`;await M.rename(i,s);let[a]=await Ot(n,{dark:!0,format:"svg",output:r,transparent:!0}),d=`${Tt(a)}-${o}-dark.svg`;if(await M.rename(a,d),o!==void 0){let m=C.basename(d),p=C.basename(s),f=p.replace(`${o}-light.svg`,""),g=await M.readdir(r);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(r,w))}}return kt(s,d,e)}}};async function kt(t,e,n){let{packageFile:r}=await b();if(r===void 0)throw new Error("No package file found");let o=C.dirname(r),i=C.relative(o,t);return`<picture>
|
|
28
29
|
<source media="(prefers-color-scheme: dark)" srcset="${C.relative(o,e)}">
|
|
29
30
|
<source media="(prefers-color-scheme: light)" srcset="${i}">
|
|
30
31
|
<img alt="${n}" src="${i}">
|
|
31
|
-
</picture>`}async function
|
|
32
|
+
</picture>`}async function Nt(t){let e=await M.readFile(t),n=_n.createHash("sha1");return n.update(e),n.digest("hex").slice(0,8)}function Tt(t){return t.replace(/\.[^./]+$/,"")}import{getSoleRule as Vn}from"remark-mdat";var xt={toc:{applicationOrder:1,content:[Vn(te)]}};var At={...J,...H,...Pt,...Et,...Y,...Lt,...bt,...W,...Z,...te,...$t,...xt,...Q};async function T(t){let e={addMetaComment:!0,rules:At},{additionalConfig:n=[],...r}=t??{},o=Array.isArray(n)?n:[n],i=await y({additionalConfig:[e,...o],...r});if(i.packageFile===void 0)throw new Error("Package file path is required in `mdat readme` config");return i}import{findUp as Jn}from"find-up";import{packageDirectory as Bn}from"pkg-dir";import{log as Mt}from"remark-mdat";async function Hn(){Mt.info("Searching for package directory...");let t=await Bn()??process.cwd(),e=await Jn("readme.md",{stopAt:t,type:"file"});if(e!==void 0)return Mt.info(`Found closest readme at "${e}"`),e}async function ne(){let t=await Hn();if(t===void 0)throw new Error("No readme found");return t}async function zn(t,e,n,r,o){return t??=await ne(),E(t,T,$,e,n,r,o)}async function qn(t,e,n){return O(t,T,$,e,n)}async function Kn(t,e,n,r,o){return t??=await ne(),E(t,T,x,e,n,r,o)}async function Gn(t,e,n){return O(t,T,x,e,n)}async function Yn(t,e,n,r,o){return t??=await ne(),E(t,T,F,e,n,r,o)}export{Qt as checkFiles,Kn as checkReadmeFiles,Gn as checkReadmeString,en as checkString,tn as collapseFiles,Yn as collapseReadmeFiles,nn as collapseString,Zt as expandFiles,zn as expandReadmeFiles,qn as expandReadmeString,Xt as expandString,y as loadConfig,T as loadConfigReadme,qt as mergeConfigs};
|
|
@@ -56,7 +56,7 @@ declare const _default: {
|
|
|
56
56
|
content(options: import("type-fest").JsonValue): Promise<string>;
|
|
57
57
|
};
|
|
58
58
|
'cli-help': {
|
|
59
|
-
content(options
|
|
59
|
+
content(options?: import("type-fest").JsonValue | undefined): Promise<string>;
|
|
60
60
|
};
|
|
61
61
|
banner: {
|
|
62
62
|
content(options?: import("type-fest").JsonValue | undefined): Promise<string>;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "mdat",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.6.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "CLI tool and library for using comments as content templates in Markdown files, with helpful presets for readmes.",
|
|
6
6
|
"repository": {
|
|
@@ -43,7 +43,7 @@
|
|
|
43
43
|
],
|
|
44
44
|
"dependencies": {
|
|
45
45
|
"@clack/prompts": "^0.7.0",
|
|
46
|
-
"@kitschpatrol/tldraw-cli": "^4.
|
|
46
|
+
"@kitschpatrol/tldraw-cli": "^4.1.0",
|
|
47
47
|
"@types/mdast": "^4.0.3",
|
|
48
48
|
"@types/unist": "^3.0.2",
|
|
49
49
|
"chalk": "^5.3.0",
|
|
@@ -51,10 +51,10 @@
|
|
|
51
51
|
"cosmiconfig": "^9.0.0",
|
|
52
52
|
"execa": "^8.0.1",
|
|
53
53
|
"find-up": "^7.0.0",
|
|
54
|
-
"globby": "^14.0.
|
|
54
|
+
"globby": "^14.0.1",
|
|
55
55
|
"is-executable": "^2.0.1",
|
|
56
56
|
"mdast-util-toc": "^7.0.0",
|
|
57
|
-
"nanoid": "^5.0.
|
|
57
|
+
"nanoid": "^5.0.6",
|
|
58
58
|
"package-up": "^5.0.0",
|
|
59
59
|
"path-type": "^5.0.0",
|
|
60
60
|
"pkg-dir": "^8.0.0",
|
|
@@ -64,21 +64,21 @@
|
|
|
64
64
|
"remark": "^15.0.1",
|
|
65
65
|
"remark-gfm": "^4.0.0",
|
|
66
66
|
"to-vfile": "^8.0.0",
|
|
67
|
-
"type-fest": "^4.10.
|
|
67
|
+
"type-fest": "^4.10.3",
|
|
68
68
|
"untildify": "^5.0.0",
|
|
69
69
|
"vfile": "^6.0.1",
|
|
70
70
|
"which": "^4.0.0",
|
|
71
71
|
"yargs": "^17.7.2",
|
|
72
72
|
"zod": "^3.22.4",
|
|
73
|
-
"remark-mdat": "0.
|
|
73
|
+
"remark-mdat": "0.6.0"
|
|
74
74
|
},
|
|
75
75
|
"devDependencies": {
|
|
76
|
-
"@types/node": "^20.11.
|
|
76
|
+
"@types/node": "^20.11.19",
|
|
77
77
|
"@types/which": "^3.0.3",
|
|
78
78
|
"@types/yargs": "^17.0.32",
|
|
79
|
-
"tsup": "^8.0.
|
|
79
|
+
"tsup": "^8.0.2",
|
|
80
80
|
"typescript": "^5.3.3",
|
|
81
|
-
"vitest": "^1.
|
|
81
|
+
"vitest": "^1.3.1"
|
|
82
82
|
},
|
|
83
83
|
"publishConfig": {
|
|
84
84
|
"access": "public"
|
|
@@ -86,7 +86,7 @@
|
|
|
86
86
|
"scripts": {
|
|
87
87
|
"build": "tsup && tsc -p tsconfig.build.json",
|
|
88
88
|
"dev": "pnpm run test",
|
|
89
|
-
"mdat": "./bin/cli.js readme --config
|
|
89
|
+
"mdat": "./bin/cli.js readme --config ../../.mdatrc.ts",
|
|
90
90
|
"pretest": "pnpm run build",
|
|
91
91
|
"test": "vitest -no-file-parallelism"
|
|
92
92
|
}
|
package/readme.md
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
<!--+ Warning: Content in HTML comment blocks generated by mdat on 2024-02-
|
|
1
|
+
<!--+ Warning: Content in HTML comment blocks generated by mdat on 2024-02-22 +-->
|
|
2
2
|
|
|
3
3
|
<!-- header -->
|
|
4
4
|
|
|
5
5
|
# mdat
|
|
6
6
|
|
|
7
|
-
[](https://npmjs.com/package/mdat)
|
|
7
|
+
[](https://npmjs.com/package/mdat)
|
|
8
8
|
[](https://opensource.org/licenses/MIT)
|
|
9
9
|
|
|
10
10
|
**CLI tool and library for using comments as content templates in Markdown files, with helpful presets for readmes.**
|
|
@@ -20,22 +20,12 @@
|
|
|
20
20
|
- [Dependencies](#dependencies)
|
|
21
21
|
- [Installation](#installation)
|
|
22
22
|
- [Features](#features)
|
|
23
|
-
- [1. Minimalist syntax](#1-minimalist-syntax)
|
|
24
|
-
- [2. Single-comment placeholders](#2-single-comment-placeholders)
|
|
25
|
-
- [3. Familiar JSON arguments](#3-familiar-json-arguments)
|
|
26
|
-
- [4. Flexible rule system](#4-flexible-rule-system)
|
|
27
|
-
- [5. TypeScript native](#5-typescript-native)
|
|
28
|
-
- [6. Validation](#6-validation)
|
|
29
|
-
- [7. Compound rules](#7-compound-rules)
|
|
30
|
-
- [8. Single-command readme workflow](#8-single-command-readme-workflow)
|
|
31
23
|
- [Usage](#usage)
|
|
32
24
|
- [CLI](#cli)
|
|
33
25
|
- [API](#api)
|
|
34
26
|
- [Configuration](#configuration)
|
|
35
|
-
- [Creating custom rules](#creating-custom-rules)
|
|
36
|
-
- [The `mdat readme` subcommand](#the-mdat-readme-subcommand)
|
|
37
|
-
- [Bundled rules](#bundled-rules)
|
|
38
|
-
- [Bundled templates](#bundled-templates)
|
|
27
|
+
- [Creating custom rules](#creating-custom-rules)
|
|
28
|
+
- [The `mdat readme` subcommand](#the-mdat-readme-subcommand)
|
|
39
29
|
- [Background](#background)
|
|
40
30
|
- [Motivation](#motivation)
|
|
41
31
|
- [Similar projects](#similar-projects)
|
|
@@ -54,9 +44,9 @@ This is a CLI tool and library implementing the Markdown Autophagic Template (md
|
|
|
54
44
|
<!-- tldraw src: "./assets/mdat-flow.tldr" -->
|
|
55
45
|
|
|
56
46
|
<picture>
|
|
57
|
-
<source media="(prefers-color-scheme: dark)" srcset="assets/mdat-flow-
|
|
58
|
-
<source media="(prefers-color-scheme: light)" srcset="assets/mdat-flow-
|
|
59
|
-
<img alt="tldraw diagram" src="assets/mdat-flow-
|
|
47
|
+
<source media="(prefers-color-scheme: dark)" srcset="assets/mdat-flow-63a3366c-dark.svg">
|
|
48
|
+
<source media="(prefers-color-scheme: light)" srcset="assets/mdat-flow-63a3366c-light.svg">
|
|
49
|
+
<img alt="tldraw diagram" src="assets/mdat-flow-63a3366c-light.svg">
|
|
60
50
|
</picture>
|
|
61
51
|
|
|
62
52
|
<!-- /tldraw -->
|
|
@@ -74,7 +64,7 @@ Given placeholder comments in a Markdown file like this:
|
|
|
74
64
|
Run your file through the tool:
|
|
75
65
|
|
|
76
66
|
```sh
|
|
77
|
-
mdat some-file.md
|
|
67
|
+
mdat readme some-file.md
|
|
78
68
|
```
|
|
79
69
|
|
|
80
70
|
To turn it into:
|
|
@@ -115,105 +105,105 @@ npm install --global remark-mdat
|
|
|
115
105
|
|
|
116
106
|
As [noted below](#similar-projects), there are several similar projects out there. This overlap is mostly the result of my mediocre due diligence before starting development, but there remain a few distinguishing aspects of this particular implementation of the idea:
|
|
117
107
|
|
|
118
|
-
|
|
108
|
+
1. **Minimalist syntax**
|
|
119
109
|
|
|
120
|
-
No screaming caps or wordy opening and closing tag keywords, just a minimal HTML-esque syntax:
|
|
110
|
+
No screaming caps or wordy opening and closing tag keywords, just a minimal HTML-esque syntax:
|
|
121
111
|
|
|
122
|
-
```md
|
|
123
|
-
<!-- title -->
|
|
112
|
+
```md
|
|
113
|
+
<!-- title -->
|
|
124
114
|
|
|
125
|
-
# mdat
|
|
115
|
+
# mdat
|
|
126
116
|
|
|
127
|
-
<!-- /title -->
|
|
128
|
-
```
|
|
117
|
+
<!-- /title -->
|
|
118
|
+
```
|
|
129
119
|
|
|
130
|
-
(Optionally, you can specify a prefix if you want to mix "true" comments with `mdat` content placeholder comments.)
|
|
120
|
+
(Optionally, you can specify a prefix if you want to mix "true" comments with `mdat` content placeholder comments.)
|
|
131
121
|
|
|
132
|
-
|
|
122
|
+
2. **Single-comment placeholders**
|
|
133
123
|
|
|
134
|
-
When you're roughing out a readme, you can drop in a single opening comment, and `mdat` will take care of expanding it and adding the closing tag the next time it's run. To generate the block shown above, you'd need only to add:
|
|
124
|
+
When you're roughing out a readme, you can drop in a single opening comment, and `mdat` will take care of expanding it and adding the closing tag the next time it's run. To generate the block shown above, you'd need only to add:
|
|
135
125
|
|
|
136
|
-
```md
|
|
137
|
-
<!-- title -->
|
|
138
|
-
```
|
|
126
|
+
```md
|
|
127
|
+
<!-- title -->
|
|
128
|
+
```
|
|
139
129
|
|
|
140
|
-
|
|
130
|
+
3. **Familiar JSON arguments**
|
|
141
131
|
|
|
142
|
-
In the rare instances when you want to pass extra data or configuration into a comment template, you just use a bit of JSON. No need to grok a custom syntax:
|
|
132
|
+
In the rare instances when you want to pass extra data or configuration into a comment template, you just use a bit of JSON. No need to grok a custom syntax:
|
|
143
133
|
|
|
144
|
-
```md
|
|
145
|
-
<!-- title { prefix: "🙃" } -->
|
|
146
|
-
```
|
|
134
|
+
```md
|
|
135
|
+
<!-- title { prefix: "🙃" } -->
|
|
136
|
+
```
|
|
147
137
|
|
|
148
|
-
Internally, comment option arguments are parsed with [JSON5](https://json5.org), so you can skip quoting keys if you like. A pre-parsing step adds another layer of leniency if you want to skip the brackets or include parentheses to pretend your keyword is a function. The expansion rules included with the `mdat readme` subcommand use [Zod](https://zod.dev) to validate the option arguments and provide helpful errors at runtime.
|
|
138
|
+
Internally, comment option arguments are parsed with [JSON5](https://json5.org), so you can skip quoting keys if you like. A pre-parsing step adds another layer of leniency if you want to skip the brackets or include parentheses to pretend your keyword is a function. The expansion rules included with the `mdat readme` subcommand use [Zod](https://zod.dev) to validate the option arguments and provide helpful errors at runtime.
|
|
149
139
|
|
|
150
|
-
|
|
140
|
+
4. **Flexible rule system**
|
|
151
141
|
|
|
152
|
-
Comment expansions definitions are referred to as "rules".
|
|
142
|
+
Comment expansions definitions are referred to as "rules".
|
|
153
143
|
|
|
154
|
-
An expansion rule can be as minimal as a file exporting a record:
|
|
144
|
+
An expansion rule can be as minimal as a file exporting a record:
|
|
155
145
|
|
|
156
|
-
```ts
|
|
157
|
-
{ keyword: "content"}`
|
|
158
|
-
```
|
|
146
|
+
```ts
|
|
147
|
+
{ keyword: "content"}`
|
|
148
|
+
```
|
|
159
149
|
|
|
160
|
-
Which will turn:
|
|
150
|
+
Which will turn:
|
|
161
151
|
|
|
162
|
-
```md
|
|
163
|
-
<!-- keyword -->
|
|
164
|
-
```
|
|
152
|
+
```md
|
|
153
|
+
<!-- keyword -->
|
|
154
|
+
```
|
|
165
155
|
|
|
166
|
-
Into:
|
|
156
|
+
Into:
|
|
167
157
|
|
|
168
|
-
```md
|
|
169
|
-
<!-- keyword -->
|
|
158
|
+
```md
|
|
159
|
+
<!-- keyword -->
|
|
170
160
|
|
|
171
|
-
content
|
|
161
|
+
content
|
|
172
162
|
|
|
173
|
-
<!-- /keyword -->
|
|
174
|
-
```
|
|
163
|
+
<!-- /keyword -->
|
|
164
|
+
```
|
|
175
165
|
|
|
176
|
-
Or, make things a bit more dynamic by returning a function instead of a string. Async functions are welcome.
|
|
166
|
+
Or, make things a bit more dynamic by returning a function instead of a string. Async functions are welcome.
|
|
177
167
|
|
|
178
|
-
```ts
|
|
179
|
-
{ date: () => `${new Date().toISOString()}` } }"
|
|
180
|
-
```
|
|
168
|
+
```ts
|
|
169
|
+
{ date: () => `${new Date().toISOString()}` } }"
|
|
170
|
+
```
|
|
181
171
|
|
|
182
|
-
Or enforce validation by adding some metadata:
|
|
172
|
+
Or enforce validation by adding some metadata:
|
|
183
173
|
|
|
184
|
-
```ts
|
|
185
|
-
{
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
}
|
|
192
|
-
```
|
|
174
|
+
```ts
|
|
175
|
+
{
|
|
176
|
+
date: {
|
|
177
|
+
content: () => `${new Date().toISOString()}`,
|
|
178
|
+
order: 1,
|
|
179
|
+
required: true,
|
|
180
|
+
},
|
|
181
|
+
}
|
|
182
|
+
```
|
|
193
183
|
|
|
194
|
-
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.
|
|
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.
|
|
195
185
|
|
|
196
|
-
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.
|
|
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.
|
|
197
187
|
|
|
198
|
-
|
|
188
|
+
5. **TypeScript native**
|
|
199
189
|
|
|
200
|
-
`mdat` exports definitions for rule types, and configuration / rule sets may be written directly in TypeScript.
|
|
190
|
+
`mdat` exports definitions for rule types, and configuration / rule sets may be written directly in TypeScript.
|
|
201
191
|
|
|
202
|
-
|
|
192
|
+
6. **Validation**
|
|
203
193
|
|
|
204
|
-
In addition to content replacement, individual rules can define validation constraints. `mdat` includes a `--check` option which runs your expanded Markdown through a validator to enforce the presence and order of appearance of your comment placeholders.
|
|
194
|
+
In addition to content replacement, individual rules can define validation constraints. `mdat` includes a `--check` option which runs your expanded Markdown through a validator to enforce the presence and order of appearance of your comment placeholders.
|
|
205
195
|
|
|
206
|
-
|
|
196
|
+
7. **Compound rules**
|
|
207
197
|
|
|
208
|
-
It's easy to create "compound" expansion rules that encapsulate a number of other individual rules into a single Markdown comment to keep the quantity of template comments in check.
|
|
198
|
+
It's easy to create "compound" expansion rules that encapsulate a number of other individual rules into a single Markdown comment to keep the quantity of template comments in check.
|
|
209
199
|
|
|
210
|
-
See the [`<!-- header -->`](./src/lib/readme/rules/header.ts) rule in the `mdat readme` subcommand for an example.
|
|
200
|
+
See the [`<!-- header -->`](./src/lib/readme/rules/header.ts) rule in the `mdat readme` subcommand for an example.
|
|
211
201
|
|
|
212
|
-
|
|
202
|
+
8. **Single-command readme workflow**
|
|
213
203
|
|
|
214
|
-
`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.
|
|
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.
|
|
215
205
|
|
|
216
|
-
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.
|
|
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.
|
|
217
207
|
|
|
218
208
|
## Usage
|
|
219
209
|
|
|
@@ -333,7 +323,7 @@ Work with `mdat` comments in your readme.md.
|
|
|
333
323
|
|
|
334
324
|
This section lists top-level commands for `mdat readme`.
|
|
335
325
|
|
|
336
|
-
If no command is provided, `mdat readme
|
|
326
|
+
If no command is provided, `mdat readme expand` is run by default.
|
|
337
327
|
|
|
338
328
|
Usage:
|
|
339
329
|
|
|
@@ -620,7 +610,7 @@ type Config = {
|
|
|
620
610
|
|
|
621
611
|
A valid configuration file default-exports an object conforming to the above type.
|
|
622
612
|
|
|
623
|
-
The configuration file may be located in any location supported by [cosmicconfig](https://github.com/cosmiconfig/cosmiconfig?tab=readme-ov-file#searchplaces). I use an
|
|
613
|
+
The configuration file may be located in any location supported by [cosmicconfig](https://github.com/cosmiconfig/cosmiconfig?tab=readme-ov-file#searchplaces). I use an `.mdatrc.ts` file in the root of my projects.
|
|
624
614
|
|
|
625
615
|
#### Rule file format
|
|
626
616
|
|
|
@@ -655,59 +645,59 @@ Since it's a record, multiple rules may be combined in single rules file.
|
|
|
655
645
|
|
|
656
646
|
If multiple configuration and rule files are loaded, they are merged. CLI options take precedence over ambient configuration discovered by cosmicconfig, and where multiple configuration or rule files are provided, with the "last" rule of a particular key takes precedence.
|
|
657
647
|
|
|
658
|
-
|
|
648
|
+
### Creating custom rules
|
|
659
649
|
|
|
660
650
|
The underlying rule expansion system is flexible and easy to extend.
|
|
661
651
|
|
|
662
652
|
See the [Examples section](../remark-mdat/readme.md#examples) of the `remark-mdat` readme, or take a look at the implementation of the [rules provided through the `mdat readme` subcommand](./src/lib/readme/rules/) for more complex examples.
|
|
663
653
|
|
|
664
|
-
|
|
654
|
+
### The `mdat readme` subcommand
|
|
665
655
|
|
|
666
|
-
|
|
656
|
+
#### Bundled rules
|
|
667
657
|
|
|
668
|
-
|
|
658
|
+
##### Stand-alone:
|
|
669
659
|
|
|
670
|
-
-
|
|
660
|
+
- ###### `<!-- title -->`
|
|
671
661
|
|
|
672
662
|
The `name` field from `package.json`.
|
|
673
663
|
|
|
674
|
-
-
|
|
664
|
+
- ###### `<!-- banner -->`
|
|
675
665
|
|
|
676
666
|
Looks for an image in the `/assets` folder for use as a banner image. Searches for a number of typical names and formats. (The assets path may be specified through configuration files or command line flags.)
|
|
677
667
|
|
|
678
|
-
-
|
|
668
|
+
- ###### `<!-- badges -->`
|
|
679
669
|
|
|
680
670
|
Generates badges based on `package.json`. Currently only supports license and NPM version badges.
|
|
681
671
|
|
|
682
|
-
-
|
|
672
|
+
- ###### `<!-- short-description -->`
|
|
683
673
|
|
|
684
674
|
The `description` field from `package.json`.
|
|
685
675
|
|
|
686
|
-
-
|
|
676
|
+
- ###### `<!-- table-of-contents -->`
|
|
687
677
|
|
|
688
678
|
A table of contents automatically generated by [mdast-util-toc](https://github.com/syntax-tree/mdast-util-toc).
|
|
689
679
|
|
|
690
680
|
This rule is also aliased under the `<!-- toc -->` keyword, if you're into the brevity thing.
|
|
691
681
|
|
|
692
|
-
-
|
|
682
|
+
- ###### `<!-- contributing -->`
|
|
693
683
|
|
|
694
684
|
Invites issues and pull request, generating links based on `package.json`.
|
|
695
685
|
|
|
696
|
-
-
|
|
686
|
+
- ###### `<!-- license -->`
|
|
697
687
|
|
|
698
688
|
Documents the project's license, based on the `license` field from `package.json`.
|
|
699
689
|
|
|
700
|
-
-
|
|
690
|
+
- ###### `<!-- code -->`
|
|
701
691
|
|
|
702
692
|
A quick way to embed a code block from elsewhere in your repository. Useful for examples.
|
|
703
693
|
|
|
704
|
-
-
|
|
694
|
+
- ###### `<!-- cli-help -->`
|
|
705
695
|
|
|
706
696
|
Automatically transform a CLI command's `--help` output into nicely formatted Markdown tables. The rule also recursively calls `--help` on any subcommands found for inclusion in the output.
|
|
707
697
|
|
|
708
698
|
Currently, the rule can only parse help output from [Yargs](https://yargs.js.org)-based tools. If parsing fails, the rule will fall back to show the help output in a regular code block.
|
|
709
699
|
|
|
710
|
-
-
|
|
700
|
+
- ###### `<!-- tldraw -->`
|
|
711
701
|
|
|
712
702
|
Allows embedding [tldraw](https://www.tldraw.com) files in your readme. Accepts either a path to a local `.tldr` file, or remote tldraw URLs.
|
|
713
703
|
|
|
@@ -719,11 +709,11 @@ See the [Examples section](../remark-mdat/readme.md#examples) of the `remark-mda
|
|
|
719
709
|
|
|
720
710
|
This rule is used to embed the diagram at the top of this readme.
|
|
721
711
|
|
|
722
|
-
|
|
712
|
+
##### Compound
|
|
723
713
|
|
|
724
714
|
Compound rules combine several stand-alone rules under a single keyword, which can help reduce comment clutter in your readme's Markdown.
|
|
725
715
|
|
|
726
|
-
-
|
|
716
|
+
- ###### `<!-- header -->`
|
|
727
717
|
|
|
728
718
|
Combines a number of rules often applied at the top of a readme into a single keyword. This rule is the equivalent of:
|
|
729
719
|
|
|
@@ -734,7 +724,7 @@ Compound rules combine several stand-alone rules under a single keyword, which c
|
|
|
734
724
|
<!-- shortDescription -->
|
|
735
725
|
```
|
|
736
726
|
|
|
737
|
-
-
|
|
727
|
+
- ###### `<!-- footer -->`
|
|
738
728
|
|
|
739
729
|
Bundles together rules often applied at the end of a readme. Just two rules at the moment:
|
|
740
730
|
|
|
@@ -743,19 +733,19 @@ Compound rules combine several stand-alone rules under a single keyword, which c
|
|
|
743
733
|
<!-- license -->
|
|
744
734
|
```
|
|
745
735
|
|
|
746
|
-
|
|
736
|
+
#### Bundled templates
|
|
747
737
|
|
|
748
738
|
The `init` command provides a number of "starter readme" templates incorporating `mdat` comment placeholders:
|
|
749
739
|
|
|
750
|
-
-
|
|
740
|
+
- ##### Mdat Readme
|
|
751
741
|
|
|
752
742
|
The house style. An expansive starting point. Prune to your context and taste. The readme files in this monorepo started from this template.
|
|
753
743
|
|
|
754
|
-
-
|
|
744
|
+
- ##### Standard Readme basic
|
|
755
745
|
|
|
756
746
|
Includes only the "required" sections from the [Standard Readme](https://github.com/RichardLitt/standard-readme/blob/main/spec.md) specification. [See an example](https://github.com/RichardLitt/standard-readme/blob/main/example-readmes/minimal-readme.md).
|
|
757
747
|
|
|
758
|
-
-
|
|
748
|
+
- ##### Standard Readme full
|
|
759
749
|
|
|
760
750
|
Includes all sections from the [Standard Readme](https://github.com/RichardLitt/standard-readme/blob/main/spec.md) specification. [See an example](https://github.com/RichardLitt/standard-readme/blob/main/example-readmes/maximal-readme.md).
|
|
761
751
|
|