` ([#6514](https://github.com/stenciljs/core/issues/6514)) ([cdcd873](https://github.com/stenciljs/core/commit/cdcd873a03de2534715320e6c758a808cab08ce1))
* **testing:** jest / mixin related errors ([#6512](https://github.com/stenciljs/core/issues/6512)) ([5c17422](https://github.com/stenciljs/core/commit/5c17422eee67ffff6f1166374e43d218ba82905f))
* **types:** components.d.ts - correctly import / export used enums ([#6522](https://github.com/stenciljs/core/issues/6522)) ([e243c6f](https://github.com/stenciljs/core/commit/e243c6f73ff8632851152b0b2f6a88eaa87c1bf4))
### Features
* **dev-server:** new `strictPort` property ([#6523](https://github.com/stenciljs/core/issues/6523)) ([cc12853](https://github.com/stenciljs/core/commit/cc1285363d85d87d5e686adcb7f5e9d93b7829b7))
* **runtime:** support tsconfig `jsxImportSource` (`h` import no longer necessary) ([#6525](https://github.com/stenciljs/core/issues/6525)) ([6482533](https://github.com/stenciljs/core/commit/648253360793cc6909aa631fe44dd34599e9d4e2))
## 🐂 [4.40.1](https://github.com/stenciljs/core/compare/v4.40.0...v4.40.1) (2025-12-23)
### Bug Fixes
* **compiler:** docs generation when using `excludedComponents` ([#6509](https://github.com/stenciljs/core/issues/6509)) ([4209437](https://github.com/stenciljs/core/commit/4209437ff371671a13fd0085611ab92abb73c1f5))
* **css:** `@container` query parsing ([#6508](https://github.com/stenciljs/core/issues/6508)) ([208a105](https://github.com/stenciljs/core/commit/208a1050c23d6de985c33d4f4a273d93e7b39a3b))
* **css:** escape backslashes ([#6506](https://github.com/stenciljs/core/issues/6506)) ([758b8ee](https://github.com/stenciljs/core/commit/758b8ee024a26da938dd335bf3c96be7269d9317))
* **runtime:** more robust `supportsConstructableStylesheets` test ([#6510](https://github.com/stenciljs/core/issues/6510)) ([484b1b8](https://github.com/stenciljs/core/commit/484b1b8682bc0ff9becedb5f180afa66e50c46fb))
# 🍌 [4.40.0](https://github.com/stenciljs/core/compare/v4.39.0...v4.40.0) (2025-12-23)
### Bug Fixes
* **compiler:** minify dist-custom-elements and hydrate-script ([#6482](https://github.com/stenciljs/core/issues/6482)) ([ec043cd](https://github.com/stenciljs/core/commit/ec043cdd0fc0fe5179e7b125039afbd034ea41a6))
* **compiler:** resolve node_modules css imports ([#6493](https://github.com/stenciljs/core/issues/6493)) ([84ac5b8](https://github.com/stenciljs/core/commit/84ac5b8cbe85be26cdf01bfa5d34fe455b853e6e))
* **css:** css imports with functions and media queries ([#6474](https://github.com/stenciljs/core/issues/6474)) ([249f84a](https://github.com/stenciljs/core/commit/249f84aab3f3597d132563907732b80d6ae1aade))
* **css:** enable parsing of native, nested css selectors ([#6480](https://github.com/stenciljs/core/issues/6480)) ([3506686](https://github.com/stenciljs/core/commit/35066867e13669ac1d19fb168e3ae85dc4dd42b6))
* **css:** pseudo-element selectors in nested media queries ([#6486](https://github.com/stenciljs/core/issues/6486)) ([20ce1ce](https://github.com/stenciljs/core/commit/20ce1ce3d5dd801f3648e5052891efff4965212b))
* **css:** strip comments before adding css to js ([#6487](https://github.com/stenciljs/core/issues/6487)) ([2892b4f](https://github.com/stenciljs/core/commit/2892b4f486f79db7ba19ab54b9c500e210cda926))
* **css:** vanilla css live-reload & added globalStyles to dev `\n\n\n This Stencil app is disabled for this browser. \n\n Developers: \n \n ES5 builds are disabled during development to take advantage of 2x faster build times. \n Please see the example below or our config docs if you would like to develop on a browser that does not fully support ES2017 and custom elements. \n Note that by default, ES5 builds and polyfills are enabled during production builds. \n When testing browsers it is recommended to always test in production mode, and ES5 builds should always be enabled during production builds. \n This is only an experiment and if it slows down app development then we will revert this and enable ES5 builds during dev. \n\n\n Enabling ES5 builds during development: \n \n npm run dev --es5\n \n For stencil-component-starter, use:
\n \n npm start --es5\n \n\n\n Enabling full production builds during development: \n \n npm run dev --prod\n \n For stencil-component-starter, use:
\n \n npm start --prod\n \n\n Current Browser\'s Support: \n \n\n Current Browser: \n \n \n';
document.getElementById('current-browser-output').textContent = window.navigator.userAgent;
document.getElementById('es-modules-test').textContent = supportsEsModules;
document.getElementById('es-dynamic-modules-test').textContent = supportsDynamicImports();
document.getElementById('shadow-dom-test').textContent = !!(document.head.attachShadow);
document.getElementById('custom-elements-test').textContent = !!(window.customElements);
document.getElementById('css-variables-test').textContent = !!(window.CSS && window.CSS.supports && window.CSS.supports('color', 'var(--c)'));
document.getElementById('fetch-test').textContent = !!(window.fetch);
} else {
document.body.innerHTML = '\n \n\n\n\n Update src/index.html \n\n Stencil recently changed how scripts are loaded in order to improve performance.
\n\n BEFORE: \n Previously, a single script was included that handled loading the correct JavaScript based on browser support.
\n \n <script src="/build/app.js"></script>\n\n \n\n AFTER: \n The index.html should now include two scripts using the modern ES Module script pattern.\n Note that only one file will actually be requested and loaded based on the browser\'s native support for ES Modules.\n For more info, please see Using JavaScript modules on the web .\n
\n \n <script type="module" src="/build/app.esm .js"></script>\n <script nomodule src="/build/app.js"></script>\n \n';
}
}
setTimeout(checkSupport);
})();
================================================
FILE: screenshot/compare/build/index.esm.js
================================================
================================================
FILE: screenshot/compare/build/p-081b0641.js
================================================
function t(t,n,r){const s=o(t,n,r),c=localStorage.getItem(s);if("string"==typeof c){const t=parseInt(c,10);if(!isNaN(t))return t}return null}function n(t,n,r,s){const c=o(t,n,r);localStorage.setItem(c,String(s))}function o(t,n,o){return`screenshot_mismatch_${t}_${n}_${o}`}export{t as g,n as s}
================================================
FILE: screenshot/compare/build/p-227a1e18.entry.js
================================================
import{r as t,h as s,g as e,c as o}from"./p-fbbae598.js";import{A as i}from"./p-e2efe0df.js";import{m as n,a as r,s as a,b as h,c,d as l,e as u,f as p,g as d,h as f,i as g,j as y,k as m,l as b,n as w,o as P,p as v}from"./p-9b6a9315.js";class O{constructor(s){t(this,s)}render(){return s("stencil-router",{class:"full-screen"},s("stencil-route-switch",null,s("stencil-route",{url:"/:buildIdA/:buildIdB",exact:!0,component:"screenshot-compare",class:"full-screen"}),s("stencil-route",{url:"/:buildId",component:"screenshot-preview",class:"full-screen"}),s("stencil-route",{url:"/",component:"screenshot-preview",exact:!0,class:"full-screen"})))}}class j{constructor(s){t(this,s),this.group=null,this.match=null,this.componentProps={},this.exact=!1,this.scrollOnNextRender=!1,this.previousMatch=null}computeMatch(t){const s=null!=this.group||null!=this.el.parentElement&&"stencil-route-switch"===this.el.parentElement.tagName.toLowerCase();if(t&&!s)return this.previousMatch=this.match,this.match=n(t.pathname,{path:this.url,exact:this.exact,strict:!0})}async loadCompleted(){let t={};this.history&&this.history.location.hash?t={scrollToId:this.history.location.hash.substr(1)}:this.scrollTopOffset&&(t={scrollTopOffset:this.scrollTopOffset}),"function"==typeof this.componentUpdated?this.componentUpdated(t):this.match&&!r(this.match,this.previousMatch)&&this.routeViewsUpdated&&this.routeViewsUpdated(t)}async componentDidUpdate(){await this.loadCompleted()}async componentDidLoad(){await this.loadCompleted()}render(){if(!this.match||!this.history)return null;const t=Object.assign({},this.componentProps,{history:this.history,match:this.match});return this.routeRender?this.routeRender(Object.assign({},t,{component:this.component})):this.component?s(this.component,Object.assign({},t)):void 0}get el(){return e(this)}static get watchers(){return{location:["computeMatch"]}}}i.injectProps(j,["location","history","historyType","routeViewsUpdated"]),j.style="stencil-route.inactive{display:none}";const L=t=>"STENCIL-ROUTE"===t.tagName;class S{constructor(s){t(this,s),this.group=((1e17*Math.random()).toString().match(/.{4}/g)||[]).join("-"),this.subscribers=[],this.queue=o(this,"queue")}componentWillLoad(){null!=this.location&&this.regenerateSubscribers(this.location)}async regenerateSubscribers(t){if(null==t)return;let s=-1;if(this.subscribers=Array.prototype.slice.call(this.el.children).filter(L).map((e,o)=>{const i=n(t.pathname,{path:e.url,exact:e.exact,strict:!0});return i&&-1===s&&(s=o),{el:e,match:i}}),-1===s)return;if(this.activeIndex===s)return void(this.subscribers[s].el.match=this.subscribers[s].match);this.activeIndex=s;const e=this.subscribers[this.activeIndex];this.scrollTopOffset&&(e.el.scrollTopOffset=this.scrollTopOffset),e.el.group=this.group,e.el.match=e.match,e.el.componentUpdated=t=>{this.queue.write(()=>{this.subscribers.forEach((t,s)=>{if(t.el.componentUpdated=void 0,s===this.activeIndex)return t.el.style.display="";this.scrollTopOffset&&(t.el.scrollTopOffset=this.scrollTopOffset),t.el.group=this.group,t.el.match=null,t.el.style.display="none"})}),this.routeViewsUpdated&&this.routeViewsUpdated(Object.assign({scrollTopOffset:this.scrollTopOffset},t))}}render(){return s("slot",null)}get el(){return e(this)}static get watchers(){return{location:["regenerateSubscribers"]}}}i.injectProps(S,["location","routeViewsUpdated"]);const U=(t,...s)=>{t||console.warn(...s)},k=()=>{let t,s=[];return{setPrompt:s=>(U(null==t,"A history supports only one prompt at a time"),t=s,()=>{t===s&&(t=null)}),confirmTransitionTo:(s,e,o,i)=>{if(null!=t){const n="function"==typeof t?t(s,e):t;"string"==typeof n?"function"==typeof o?o(n,i):(U(!1,"A history needs a getUserConfirmation function in order to use a prompt message"),i(!0)):i(!1!==n)}else i(!0)},appendListener:t=>{let e=!0;const o=(...s)=>{e&&t(...s)};return s.push(o),()=>{e=!1,s=s.filter(t=>t!==o)}},notifyListeners:(...t)=>{s.forEach(s=>s(...t))}}},H=(t,s="scrollPositions")=>{let e=new Map;const o=(s,o)=>{if(e.set(s,o),a(t,"sessionStorage")){const s=[];e.forEach((t,e)=>{s.push([e,t])}),t.sessionStorage.setItem("scrollPositions",JSON.stringify(s))}};if(a(t,"sessionStorage")){const o=t.sessionStorage.getItem(s);e=o?new Map(JSON.parse(o)):e}return"scrollRestoration"in t.history&&(history.scrollRestoration="manual"),{set:o,get:t=>e.get(t),has:t=>e.has(t),capture:s=>{o(s,[t.scrollX,t.scrollY])}}},T={hashbang:{encodePath:t=>"!"===t.charAt(0)?t:"!/"+P(t),decodePath:t=>"!"===t.charAt(0)?t.substr(1):t},noslash:{encodePath:P,decodePath:u},slash:{encodePath:u,decodePath:u}},E=(t,s)=>{const e=0==t.pathname.indexOf(s)?"/"+t.pathname.slice(s.length):t.pathname;return Object.assign({},t,{pathname:e})},A={browser:(t,s={})=>{let e=!1;const o=t.history,i=t.location,n=t.navigator,r=h(t),a=!c(n),w=H(t),P=null!=s.forceRefresh&&s.forceRefresh,v=null!=s.getUserConfirmation?s.getUserConfirmation:m,O=null!=s.keyLength?s.keyLength:6,j=s.basename?l(u(s.basename)):"",L=()=>{try{return t.history.state||{}}catch(t){return{}}},S=t=>{t=t||{};const{key:s,state:e}=t,{pathname:o,search:n,hash:r}=i;let a=o+n+r;return U(!j||f(a,j),'You are attempting to use a basename on a page whose URL path does not begin with the basename. Expected path "'+a+'" to begin with "'+j+'".'),j&&(a=g(a,j)),p(a,e,s||d(O))},T=k(),E=t=>{w.capture(q.location.key),Object.assign(q,t),q.location.scrollPosition=w.get(q.location.key),q.length=o.length,T.notifyListeners(q.location,q.action)},A=t=>{b(n,t)||C(S(t.state))},x=()=>{C(S(L()))},C=t=>{if(e)e=!1,E();else{const s="POP";T.confirmTransitionTo(t,s,v,e=>{e?E({action:s,location:t}):R(t)})}},R=t=>{let s=B.indexOf(q.location.key),o=B.indexOf(t.key);-1===s&&(s=0),-1===o&&(o=0);const i=s-o;i&&(e=!0,N(i))},M=S(L());let B=[M.key],I=0,_=!1;const Y=t=>j+y(t),N=t=>{o.go(t)},V=s=>{I+=s,1===I?(t.addEventListener("popstate",A),a&&t.addEventListener("hashchange",x)):0===I&&(t.removeEventListener("popstate",A),a&&t.removeEventListener("hashchange",x))},q={length:o.length,action:"POP",location:M,createHref:Y,push:(t,s)=>{U(!("object"==typeof t&&void 0!==t.state&&void 0!==s),"You should avoid providing a 2nd state argument to push when the 1st argument is a location-like object that already has state; it is ignored");const e=p(t,s,d(O),q.location);T.confirmTransitionTo(e,"PUSH",v,t=>{if(!t)return;const s=Y(e),{key:n,state:a}=e;if(r)if(o.pushState({key:n,state:a},"",s),P)i.href=s;else{const t=B.indexOf(q.location.key),s=B.slice(0,-1===t?0:t+1);s.push(e.key),B=s,E({action:"PUSH",location:e})}else U(void 0===a,"Browser history cannot push state in browsers that do not support HTML5 history"),i.href=s})},replace:(t,s)=>{U(!("object"==typeof t&&void 0!==t.state&&void 0!==s),"You should avoid providing a 2nd state argument to replace when the 1st argument is a location-like object that already has state; it is ignored");const e=p(t,s,d(O),q.location);T.confirmTransitionTo(e,"REPLACE",v,t=>{if(!t)return;const s=Y(e),{key:n,state:a}=e;if(r)if(o.replaceState({key:n,state:a},"",s),P)i.replace(s);else{const t=B.indexOf(q.location.key);-1!==t&&(B[t]=e.key),E({action:"REPLACE",location:e})}else U(void 0===a,"Browser history cannot replace state in browsers that do not support HTML5 history"),i.replace(s)})},go:N,goBack:()=>N(-1),goForward:()=>N(1),block:(t="")=>{const s=T.setPrompt(t);return _||(V(1),_=!0),()=>(_&&(_=!1,V(-1)),s())},listen:t=>{const s=T.appendListener(t);return V(1),()=>{V(-1),s()}},win:t};return q},hash:(t,s={})=>{let e=!1,o=null,i=0,n=!1;const r=t.location,a=t.history,h=w(t.navigator),c=null!=s.keyLength?s.keyLength:6,{getUserConfirmation:b=m,hashType:P="slash"}=s,O=s.basename?l(u(s.basename)):"",{encodePath:j,decodePath:L}=T[P],S=()=>{const t=r.href,s=t.indexOf("#");return-1===s?"":t.substring(s+1)},H=t=>{const s=r.href.indexOf("#");r.replace(r.href.slice(0,s>=0?s:0)+"#"+t)},E=()=>{let t=L(S());return U(!O||f(t,O),'You are attempting to use a basename on a page whose URL path does not begin with the basename. Expected path "'+t+'" to begin with "'+O+'".'),O&&(t=g(t,O)),p(t,void 0,d(c))},A=k(),x=t=>{Object.assign(q,t),q.length=a.length,A.notifyListeners(q.location,q.action)},C=()=>{const t=S(),s=j(t);if(t!==s)H(s);else{const t=E(),s=q.location;if(!e&&v(s,t))return;if(o===y(t))return;o=null,R(t)}},R=t=>{if(e)e=!1,x();else{const s="POP";A.confirmTransitionTo(t,s,b,e=>{e?x({action:s,location:t}):M(t)})}},M=t=>{let s=Y.lastIndexOf(y(q.location)),o=Y.lastIndexOf(y(t));-1===s&&(s=0),-1===o&&(o=0);const i=s-o;i&&(e=!0,N(i))},B=S(),I=j(B);B!==I&&H(I);const _=E();let Y=[y(_)];const N=t=>{U(h,"Hash history go(n) causes a full page reload in this browser"),a.go(t)},V=(t,s)=>{i+=s,1===i?t.addEventListener("hashchange",C):0===i&&t.removeEventListener("hashchange",C)},q={length:a.length,action:"POP",location:_,createHref:t=>"#"+j(O+y(t)),push:(t,s)=>{U(void 0===s,"Hash history cannot push state; it is ignored");const e=p(t,void 0,d(c),q.location);A.confirmTransitionTo(e,"PUSH",b,t=>{if(!t)return;const s=y(e),i=j(O+s);if(S()!==i){o=s,(t=>{r.hash=t})(i);const t=Y.lastIndexOf(y(q.location)),n=Y.slice(0,-1===t?0:t+1);n.push(s),Y=n,x({action:"PUSH",location:e})}else U(!1,"Hash history cannot PUSH the same path; a new entry will not be added to the history stack"),x()})},replace:(t,s)=>{U(void 0===s,"Hash history cannot replace state; it is ignored");const e=p(t,void 0,d(c),q.location);A.confirmTransitionTo(e,"REPLACE",b,t=>{if(!t)return;const s=y(e),i=j(O+s);S()!==i&&(o=s,H(i));const n=Y.indexOf(y(q.location));-1!==n&&(Y[n]=s),x({action:"REPLACE",location:e})})},go:N,goBack:()=>N(-1),goForward:()=>N(1),block:(s="")=>{const e=A.setPrompt(s);return n||(V(t,1),n=!0),()=>(n&&(n=!1,V(t,-1)),e())},listen:s=>{const e=A.appendListener(s);return V(t,1),()=>{V(t,-1),e()}},win:t};return q}};class x{constructor(s){t(this,s),this.root="/",this.historyType="browser",this.titleSuffix="",this.routeViewsUpdated=(t={})=>{if(this.history&&t.scrollToId&&"browser"===this.historyType){const s=this.history.win.document.getElementById(t.scrollToId);if(s)return s.scrollIntoView()}this.scrollTo(t.scrollTopOffset||this.scrollTopOffset)},this.isServer=o(this,"isServer"),this.queue=o(this,"queue")}componentWillLoad(){this.history=A[this.historyType](this.el.ownerDocument.defaultView),this.history.listen(t=>{t=E(t,this.root),this.location=t}),this.location=E(this.history.location,this.root)}scrollTo(t){const s=this.history;if(null!=t&&!this.isServer&&s)return"POP"===s.action&&Array.isArray(s.location.scrollPosition)?this.queue.write(()=>{s&&s.location&&Array.isArray(s.location.scrollPosition)&&s.win.scrollTo(s.location.scrollPosition[0],s.location.scrollPosition[1])}):this.queue.write(()=>{s.win.scrollTo(0,t)})}render(){if(this.location&&this.history)return s(i.Provider,{state:{historyType:this.historyType,location:this.location,titleSuffix:this.titleSuffix,root:this.root,history:this.history,routeViewsUpdated:this.routeViewsUpdated}},s("slot",null))}get el(){return e(this)}}export{O as app_root,j as stencil_route,S as stencil_route_switch,x as stencil_router}
================================================
FILE: screenshot/compare/build/p-2c298727.entry.js
================================================
import{r as e,h as t}from"./p-fbbae598.js";class s{constructor(t){e(this,t),this.appSrcUrl="",this.imagesUrl="/data/images/",this.buildsUrl="/data/builds/"}async componentWillLoad(){let e="master";this.match&&this.match.params.buildId&&(e=this.match.params.buildId.substr(0,7));let t=`${this.buildsUrl}${e}.json`;"master"===e&&(t+="?ts="+Date.now());const s=await fetch(t);s.ok&&(this.build=await s.json(),document.title=`${this.build.id} Preview: ${this.build.message}`)}render(){const e=[];return this.build&&this.build.screenshots.forEach(t=>{const s=t.testPath.split("/");s.pop();const i=`/data/tests/${this.build.id}/${s.join("/")}/`;if(!e.some(e=>e.url===i)){const s={desc:t.desc.split(",")[0],url:i};e.push(s)}}),e.sort((e,t)=>e.desc.toLowerCase()t.desc.toLowerCase()?1:0),[t("compare-header",{appSrcUrl:this.appSrcUrl}),t("section",{class:"scroll-y"},t("section",{class:"content"},this.build?t("h1",null,t("a",{href:this.build.url},this.build.message)):null,e.map(e=>t("div",null,t("a",{href:e.url},e.desc)))))]}}s.style="screenshot-preview{display:block}screenshot-preview .scroll-y{width:100%}screenshot-preview h1{color:var(--analysis-data-color);font-size:16px;margin:0}screenshot-preview .content{padding:80px 20px 140px 20px}screenshot-preview a{display:block;padding:8px;color:var(--analysis-data-color);text-decoration:none}screenshot-preview a:hover{text-decoration:underline}screenshot-preview compare-header{left:0;padding:0;width:100%;width:100%;height:auto;padding-top:env(safe-area-inset-top)}screenshot-preview compare-header compare-filter{display:none}@media (max-width: 480px){screenshot-preview a{padding:12px;font-size:18px}screenshot-preview a:hover{text-decoration:none}}";export{s as screenshot_preview}
================================================
FILE: screenshot/compare/build/p-5479268c.entry.js
================================================
import{r as t,h as s}from"./p-fbbae598.js";import{g as i}from"./p-081b0641.js";function e(t,s){const i=Object.assign({},t,s),e=Object.keys(i),o=[];return e.map(t=>{const s=i[t];!0===s?o.push(t):null!=s&&""!==s&&o.push(t+"-"+s)}),window.location.hash=o.sort().join(";"),i}class o{constructor(s){t(this,s),this.appSrcUrl="",this.imagesUrl="/data/images/",this.buildsUrl="/data/builds/",this.comparesUrl="/data/compares/",this.jsonpUrl=null,this.diffs=[]}async componentWillLoad(){this.match&&this.match.params.buildIdA&&this.match.params.buildIdB&&await this.loadBuilds(this.match.params.buildIdA,this.match.params.buildIdB),this.diffs=await function(t,s,e){const o=[];return s&&e?(e.screenshots.forEach(s=>{o.push({id:s.id,desc:s.desc,testPath:s.testPath,imageA:null,imageUrlA:null,imageB:s.image,imageUrlB:`${t}${s.image}`,identical:!1,comparable:!1,mismatchedPixels:null,width:s.width,height:s.height,deviceScaleFactor:s.deviceScaleFactor,device:s.device||s.userAgent,show:!1,hasIntersected:!1,threshold:"number"==typeof s.threshold?s.threshold:.05})}),s.screenshots.forEach(s=>{const i=o.find(t=>t.id===s.id);i&&(i.imageA=s.image,i.imageUrlA=`${t}${s.image}`)}),o.forEach(t=>{if(t.comparable=null!=t.imageA&&null!=t.imageB,t.identical=t.comparable&&t.imageA===t.imageB,t.identical)t.mismatchedPixels=0;else{const s=i(t.imageA,t.imageB,t.threshold);"number"==typeof s&&(t.mismatchedPixels=s,0===t.mismatchedPixels&&(t.identical=!0))}}),o):o}(this.imagesUrl,this.a,this.b),this.filter=function(){const t={},s=location.hash.replace("#","");return""!==s&&s.split(";").forEach(s=>{const i=s.split("-");t[i[0]]=!(i.length>1)||i[1]}),t}(),this.updateDiffs()}componentDidLoad(){if("IntersectionObserver"in window){const t={root:document.querySelector(".scroll-y"),rootMargin:"1200px"},s=new IntersectionObserver(t=>{let s=!1;t.forEach(t=>{if(t.isIntersecting){const i=this.diffs.find(s=>t.target.id==="d-"+s.id);i&&(i.hasIntersected=!0,s=!0)}}),s&&(window.requestIdleCallback?window.requestIdleCallback(()=>{this.updateDiffs()}):window.requestAnimationFrame(()=>{this.updateDiffs()}))},t),i=document.querySelectorAll("compare-row");for(let t=0;t{t.hasIntersected=!0}),this.updateDiffs();this.filter&&this.filter.diff&&this.navToDiff(this.filter.diff)}async loadBuilds(t,s){let i=`${this.buildsUrl}${t}.json`;"master"===t&&(i+="?ts="+Date.now());let e=`${this.buildsUrl}${s}.json`;"master"===s&&(e+="?ts="+Date.now());const o=await Promise.all([fetch(i),fetch(e)]),n=await o[0],a=await o[1];n.ok&&a.ok&&(this.a=await n.json(),this.b=await a.json())}filterChange(t){this.filter=e(this.filter,t.detail),this.updateDiffs()}diffNavChange(t){const s=t.detail;this.filter=e(this.filter,{diff:s}),this.updateDiffs(),this.navToDiff(s)}navToDiff(t){const s=document.getElementById("d-"+t),i=document.querySelector(".scroll-y");s&&i&&(i.scrollTop=s.offsetTop-84)}compareLoaded(t){const s=t.detail,i=this.diffs.find(t=>t.id===s.id);i&&(i.mismatchedPixels=s.mismatchedPixels),this.updateDiffs()}updateDiffs(){var t;this.diffs=(t=this.filter,this.diffs.map(s=>(s=Object.assign({},s),function(t,s){const i=!t.device||t.device===s.device,e=!t.search||s.desc.includes(t.search);let o=!0;return t.diff&&t.diff===s.id?o=!0:t.mismatch?null!=s.mismatchedPixels&&"all"!==t.mismatch&&(o=parseInt(t.mismatch,10)0||null==s.mismatchedPixels,s.show=i&&e&&o,s}(t,s))).sort((t,s)=>t.mismatchedPixels>s.mismatchedPixels?-1:t.mismatchedPixelss.desc.toLowerCase()?1:t.device.toLowerCase()s.device.toLowerCase()?1:0))}render(){return[s("compare-header",{diffs:this.diffs,filter:this.filter,appSrcUrl:this.appSrcUrl}),s("section",{class:"scroll-x"},s("compare-thead",{a:this.a,b:this.b,diffs:this.diffs}),s("section",{class:"scroll-y"},s("compare-table",null,s("compare-tbody",null,this.diffs.map(t=>s("compare-row",{key:t.id,aId:this.a.id,bId:this.b.id,id:"d-"+t.id,show:t.show,hidden:!t.show,imagesUrl:this.imagesUrl,jsonpUrl:this.jsonpUrl,diff:t}))))))]}}export{o as screenshot_compare}
================================================
FILE: screenshot/compare/build/p-573ec8a4.entry.js
================================================
import{r as l,d as t,h as d}from"./p-fbbae598.js";class a{constructor(d){l(this,d),this.mismatchedPixels=null,this.diffNavChange=t(this,"diffNavChange",7)}navToDiff(l){l.preventDefault(),l.stopPropagation(),this.diffNavChange.emit(this.diff.id)}render(){const l=this.diff,t="number"==typeof this.mismatchedPixels,a=t?this.mismatchedPixels/(l.width*l.deviceScaleFactor*(l.height*l.deviceScaleFactor)):null;let i="";t?this.mismatchedPixels>0&&(i="has-mismatch"):i="not-calculated";const n=l.testPath.split("/");n.pop();const s=n.join("/");return[d("p",{class:"test-path"},l.testPath),d("dl",null,d("div",null,d("dt",null,"Diff"),d("dd",null,d("a",{href:"#diff-"+l.id,onClick:this.navToDiff.bind(this)},l.id))),l.comparable?[d("div",{class:i},d("dt",null,"Mismatched Pixels"),d("dd",null,t?this.mismatchedPixels:"--")),d("div",{class:i},d("dt",null,"Mismatched Ratio"),d("dd",null,t?a.toFixed(4):"--"))]:null,d("div",null,d("dt",null,"Device"),d("dd",null,l.device)),d("div",null,d("dt",null,"Width"),d("dd",null,l.width)),d("div",null,d("dt",null,"Height"),d("dd",null,l.height)),d("div",null,d("dt",null,"Device Scale Factor"),d("dd",null,l.deviceScaleFactor)),l.imageA?d("div",null,d("dt",null,"Left Preview"),d("dd",null,d("a",{href:`/data/tests/${this.aId}/${s}/`,target:"_blank"},"HTML"))):null,l.imageB?d("div",null,d("dt",null,"Right Preview"),d("dd",null,d("a",{href:`/data/tests/${this.bId}/${s}/`,target:"_blank"},"HTML"))):null,d("div",{class:"desc"},d("dt",null,"Description"),d("dd",null,l.desc)))]}}a.style=".test-path{margin-top:0;padding-top:0;font-size:10px;color:var(--analysis-data-color)}dl{padding:0;margin:0;font-size:var(--analysis-data-font-size);line-height:28px}div{display:flex;width:260px}dt{display:inline;flex:2;font-weight:500}dd{display:inline;flex:1;color:var(--analysis-data-color)}.desc,.desc dt{display:block}.desc dd{display:block;margin:0;line-height:22px}.not-calculated dd{color:#cccccc}.has-mismatch dd{color:#ff6200}p{padding-top:14px;font-size:var(--analysis-data-font-size)}a{color:var(--analysis-data-color)}a:hover{text-decoration:none}";export{a as compare_analysis}
================================================
FILE: screenshot/compare/build/p-6ba08604.entry.js
================================================
import{r as t,h as i}from"./p-fbbae598.js";class o{constructor(i){t(this,i),this.a="",this.b=""}async componentWillLoad(){const t="/data/builds/master.json?ts="+Date.now(),i=await fetch(t);i.ok&&(this.build=await i.json())}onSubmit(t){t.preventDefault(),t.stopPropagation();let i=this.a.trim().toLowerCase(),o=this.b.trim().toLowerCase();i&&o&&(i=i.substring(0,7),o=o.substring(0,7),window.location.href=`/${i}/${o}`)}render(){return[i("header",null,i("div",{class:"logo"},i("a",{href:"/"},i("img",{src:"/assets/logo.png?1"})))),i("section",null,this.build?i("section",{class:"master"},i("p",null,i("a",{href:"/master"},this.build.message))):null,i("form",{onSubmit:this.onSubmit.bind(this)},i("div",null,i("input",{onInput:t=>this.a=t.target.value})),i("div",null,i("input",{onInput:t=>this.b=t.target.value})),i("div",null,i("button",{type:"submit"},"Compare Screenshots"))))]}}o.style="header{padding:8px;background:white;box-shadow:var(--header-box-shadow)}img{width:174px;height:32px}.logo{flex:1;padding:7px}a{padding:8px;color:var(--analysis-data-color);text-decoration:none}.master{text-align:center}a:hover{text-decoration:underline}form{width:160px;margin:40px auto}form div{margin:10px}input{width:100%}";export{o as screenshot_lookup}
================================================
FILE: screenshot/compare/build/p-6bc63295.entry.js
================================================
import{r as s,g as t}from"./p-fbbae598.js";import{A as e}from"./p-e2efe0df.js";class i{constructor(t){s(this,t),this.when=!0,this.message=""}enable(s){this.unblock&&this.unblock(),this.history&&(this.unblock=this.history.block(s))}disable(){this.unblock&&(this.unblock(),this.unblock=void 0)}componentWillLoad(){this.when&&this.enable(this.message)}updateMessage(s,t){this.when?this.when&&t===s||this.enable(this.message):this.disable()}componentDidUnload(){this.disable()}render(){return null}get el(){return t(this)}static get watchers(){return{message:["updateMessage"],when:["updateMessage"]}}}e.injectProps(i,["history"]);export{i as stencil_router_prompt}
================================================
FILE: screenshot/compare/build/p-7a3759fd.entry.js
================================================
import{r as e,d as t,h as i}from"./p-fbbae598.js";class s{constructor(i){e(this,i),this.filterChange=t(this,"filterChange",7)}render(){if(!this.diffs||0===this.diffs.length||!this.filter)return;const e=this.diffs.reduce((e,t)=>(e.some(e=>e.value===t.device)||e.push({text:t.device,value:t.device}),e),[{text:"All Devices",value:""}]);return i("section",null,i("div",{class:"showing"},"Showing ",this.diffs.filter(e=>e.show).length),i("div",{class:"search"},i("input",{type:"search",onInput:e=>{this.filterChange.emit({search:e.target.value})},value:this.filter.search||""})),e.length>1?i("div",{class:"device"},i("select",{onInput:e=>{this.filterChange.emit({device:e.target.value})}},e.map(e=>i("option",{key:e.value,selected:e.value===this.filter.device,value:e.value},e.text)))):null,i("div",{class:"mismatch"},i("select",{onInput:e=>{this.filterChange.emit({mismatch:e.target.value})}},i("option",{value:"",selected:""===this.filter.mismatch},"> 0"),i("option",{value:"100",selected:"100"===this.filter.mismatch},"> 100"),i("option",{value:"250",selected:"250"===this.filter.mismatch},"> 250"),i("option",{value:"500",selected:"500"===this.filter.mismatch},"> 500"),i("option",{value:"1000",selected:"1000"===this.filter.mismatch},"> 1,000"),i("option",{value:"2500",selected:"2500"===this.filter.mismatch},"> 2,500"),i("option",{value:"5000",selected:"5000"===this.filter.mismatch},"> 5,000"),i("option",{value:"10000",selected:"10000"===this.filter.mismatch},"> 10,000"),i("option",{value:"25000",selected:"25000"===this.filter.mismatch},"> 25,000"),i("option",{value:"50000",selected:"50000"===this.filter.mismatch},"> 50,000"),i("option",{value:"all",selected:"all"===this.filter.mismatch},"All Screenshots"))))}}s.style="select{font-size:10px}input{font-size:10px}.showing{font-size:12px;white-space:nowrap;margin:17px 8px 0 0;color:var(--analysis-data-color)}section{display:flex;justify-content:flex-end}.search{margin:13px 8px 0 0}.device{margin:13px 8px 0 0}.mismatch{margin:13px 8px 0 0}";class a{constructor(t){e(this,t)}render(){return[i("header",null,i("div",{class:"logo"},i("a",{href:"/"},i("img",{src:this.appSrcUrl+"/assets/logo.png?1"}))),i("compare-filter",{diffs:this.diffs,filter:this.filter}))]}}a.style=":host{background:white;box-shadow:var(--header-box-shadow)}nav{padding:4px 4px}nav a{font-size:14px;text-decoration:none;color:var(--breadcrumb-color);display:inline-block;padding:0 4px 0 4px}nav a:hover{text-decoration:underline}header{display:flex;width:calc(100% - 115px);padding:8px}img{width:174px;height:32px}.logo{flex:1;padding:7px}compare-filter{flex:1}h1{margin:0;padding:0;font-size:18px}";export{s as compare_filter,a as compare_header}
================================================
FILE: screenshot/compare/build/p-7b4e3ba7.js
================================================
import{p as e,b as r}from"./p-fbbae598.js";e().then(e=>r([["p-5479268c",[[0,"screenshot-compare",{appSrcUrl:[1,"app-src-url"],imagesUrl:[1,"images-url"],buildsUrl:[1,"builds-url"],comparesUrl:[1,"compares-url"],jsonpUrl:[1,"jsonp-url"],match:[16],a:[1040],b:[1040],filter:[32],diffs:[32]},[[0,"filterChange","filterChange"],[0,"diffNavChange","diffNavChange"],[0,"compareLoaded","compareLoaded"]]]]],["p-2c298727",[[0,"screenshot-preview",{appSrcUrl:[1,"app-src-url"],imagesUrl:[1,"images-url"],buildsUrl:[1,"builds-url"],match:[16]}]]],["p-f0b99977",[[0,"context-consumer",{context:[16],renderer:[16],subscribe:[16],unsubscribe:[32]}]]],["p-6ba08604",[[1,"screenshot-lookup"]]],["p-ec2f13e0",[[0,"stencil-async-content",{documentLocation:[1,"document-location"],content:[32]}]]],["p-d1bf53f5",[[4,"stencil-route-link",{url:[1],urlMatch:[1,"url-match"],activeClass:[1,"active-class"],exact:[4],strict:[4],custom:[1],anchorClass:[1,"anchor-class"],anchorRole:[1,"anchor-role"],anchorTitle:[1,"anchor-title"],anchorTabIndex:[1,"anchor-tab-index"],anchorId:[1,"anchor-id"],history:[16],location:[16],root:[1],ariaHaspopup:[1,"aria-haspopup"],ariaPosinset:[1,"aria-posinset"],ariaSetsize:[2,"aria-setsize"],ariaLabel:[1,"aria-label"],match:[32]}]]],["p-b4cc611c",[[0,"stencil-route-title",{titleSuffix:[1,"title-suffix"],pageTitle:[1,"page-title"]}]]],["p-6bc63295",[[0,"stencil-router-prompt",{when:[4],message:[1],history:[16],unblock:[32]}]]],["p-e8ca6d97",[[0,"stencil-router-redirect",{history:[16],root:[1],url:[1]}]]],["p-573ec8a4",[[1,"compare-analysis",{aId:[1,"a-id"],bId:[1,"b-id"],diff:[16],mismatchedPixels:[2,"mismatched-pixels"]}]]],["p-f4745c2f",[[0,"compare-row",{aId:[1,"a-id"],bId:[1,"b-id"],imagesUrl:[1,"images-url"],jsonpUrl:[1,"jsonp-url"],diff:[16],show:[4],imageASrc:[32],imageBSrc:[32],imageAClass:[32],imageBClass:[32],canvasClass:[32]}],[1,"compare-thead",{a:[16],b:[16],diffs:[16]}]]],["p-227a1e18",[[0,"app-root"],[0,"stencil-route",{group:[513],componentUpdated:[16],match:[1040],url:[1],component:[1],componentProps:[16],exact:[4],routeRender:[16],scrollTopOffset:[2,"scroll-top-offset"],routeViewsUpdated:[16],location:[16],history:[16],historyType:[1,"history-type"]}],[4,"stencil-route-switch",{group:[513],scrollTopOffset:[2,"scroll-top-offset"],location:[16],routeViewsUpdated:[16]}],[4,"stencil-router",{root:[1],historyType:[1,"history-type"],titleSuffix:[1,"title-suffix"],scrollTopOffset:[2,"scroll-top-offset"],location:[32],history:[32]}]]],["p-7a3759fd",[[1,"compare-header",{appSrcUrl:[1,"app-src-url"],diffs:[16],filter:[16]}],[1,"compare-filter",{diffs:[16],filter:[16]}]]]],e));
================================================
FILE: screenshot/compare/build/p-988eb362.css
================================================
:root{--font-family:-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;--font-color:rgb(32, 32, 32);--background-color:#f7f8fb;--breadcrumb-color:#8e9bb2;--header-box-shadow:0px 1px 4px rgba(0, 12, 32, 0.12), 0px 1px 0px rgba(0,12,32,0.02);--screenshot-box-shadow:0px 0px 4px rgba(0, 0, 0, 0.08), 0px 1px 3px rgba(0,0,0,0.12);--screenshot-border-radius:4px;--analysis-data-font-size:12px;--analysis-data-color:rgb(111, 111, 111)}*{box-sizing:border-box}body{padding:0;margin:0;font-family:var(--font-family);background:var(--background-color);color:var(--font-color)}compare-table{display:table;width:100%;margin-top:84px;margin-bottom:12px}compare-tbody{display:table-row-group}compare-tbody compare-cell{padding-top:12px}compare-row{display:table-row}compare-row[hidden]{display:none}compare-cell{display:table-cell;vertical-align:top;padding:3px 10px}body{overflow:hidden;position:absolute;width:100%;height:100vh}screenshot-compare{position:absolute;display:block;top:0px;width:100%;height:100vh}compare-header{display:block;position:absolute;z-index:1;display:block;top:0;left:-100px;padding-left:100px;width:calc(100% + 200px);height:84px}compare-thead{position:relative;top:64px;z-index:1}.scroll-x{position:absolute;top:0;width:100%;height:100vh;overflow-x:scroll;overflow-y:hidden}.scroll-y{position:absolute;top:0;height:100vh;overflow-x:hidden;overflow-y:scroll;-webkit-overflow-scrolling:touch;will-change:scroll-position}
================================================
FILE: screenshot/compare/build/p-9b6a9315.js
================================================
const r=new RegExp(["(\\\\.)","(?:\\:(\\w+)(?:\\(((?:\\\\.|[^\\\\()])+)\\))?|\\(((?:\\\\.|[^\\\\()])+)\\))([+*?])?"].join("|"),"g"),e=r=>r.replace(/([.+*?=^!:${}()[\]|/\\])/g,"\\$1"),t=r=>r.replace(/([=!:$/()])/g,"\\$1"),n=r=>r&&r.sensitive?"":"i",a=(r,t,a)=>{for(var o=(a=a||{}).strict,s=!1!==a.end,i=e(a.delimiter||"/"),l=a.delimiters||"./",c=[].concat(a.endsWith||[]).map(e).concat("$").join("|"),u="",f=!1,p=0;p-1;else{var h=e(d.prefix||""),v=d.repeat?"(?:"+d.pattern+")(?:"+h+"(?:"+d.pattern+"))*":d.pattern;t&&t.push(d),u+=d.optional?d.partial?h+"("+v+")?":"(?:"+h+"("+v+"))?":h+"("+v+")"}}return s?(o||(u+="(?:"+i+")?"),u+="$"===c?"$":"(?="+c+")"):(o||(u+="(?:"+i+"(?="+c+"))?"),f||(u+="(?="+i+"|"+c+")")),new RegExp("^"+u,n(a))},o=(s,i,l)=>s instanceof RegExp?((r,e)=>{if(!e)return r;var t=r.source.match(/\((?!\?)/g);if(t)for(var n=0;n{for(var a=[],s=0;sa(((n,a)=>{for(var o,s=[],i=0,l=0,c="",u=a&&a.delimiter||"/",f=a&&a.delimiters||"./",p=!1;null!==(o=r.exec(n));){var d=o[0],h=o[1],v=o.index;if(c+=n.slice(l,v),l=v+d.length,h)c+=h[1],p=!0;else{var g="",y=n[l],E=o[2],x=o[3],R=o[4],m=o[5];if(!p&&c.length){var $=c.length-1;f.indexOf(c[$])>-1&&(g=c[$],c=c.slice(0,$))}c&&(s.push(c),c="",p=!1);var O=g||u,_=x||R;s.push({name:E||i++,prefix:g,delimiter:O,optional:"?"===m||"*"===m,repeat:"+"===m||"*"===m,partial:""!==g&&void 0!==y&&y!==g,pattern:_?t(_):"[^"+e(O)+"]+?"})}}return(c||lnew RegExp("^"+e+"(\\/|\\?|#|$)","i").test(r),i=(r,e)=>s(r,e)?r.substr(e.length):r,l=r=>"/"===r.charAt(r.length-1)?r.slice(0,-1):r,c=r=>"/"===r.charAt(0)?r:"/"+r,u=r=>"/"===r.charAt(0)?r.substr(1):r,f=r=>{const{pathname:e,search:t,hash:n}=r;let a=e||"/";return t&&"?"!==t&&(a+="?"===t.charAt(0)?t:"?"+t),n&&"#"!==n&&(a+="#"===n.charAt(0)?n:"#"+n),a},p=r=>"/"===r.charAt(0),d=r=>Math.random().toString(36).substr(2,r),h=(r,e)=>{for(let t=e,n=t+1,a=r.length;n{if(r===e)return!0;if(null==r||null==e)return!1;if(Array.isArray(r))return Array.isArray(e)&&r.length===e.length&&r.every((r,t)=>v(r,e[t]));const t=typeof r;if(t!==typeof e)return!1;if("object"===t){const t=r.valueOf(),n=e.valueOf();if(t!==r||n!==e)return v(t,n);const a=Object.keys(r),o=Object.keys(e);return a.length===o.length&&a.every(t=>v(r[t],e[t]))}return!1},g=(r,e)=>r.pathname===e.pathname&&r.search===e.search&&r.hash===e.hash&&r.key===e.key&&v(r.state,e.state),y=(r,e,t,n)=>{let a;"string"==typeof r?(a=(r=>{let e=r||"/",t="",n="";const a=e.indexOf("#");-1!==a&&(n=e.substr(a),e=e.substr(0,a));const o=e.indexOf("?");return-1!==o&&(t=e.substr(o),e=e.substr(0,o)),{pathname:e,search:"?"===t?"":t,hash:"#"===n?"":n,query:{},key:""}})(r),void 0!==e&&(a.state=e)):(a=Object.assign({pathname:""},r),a.search&&"?"!==a.search.charAt(0)&&(a.search="?"+a.search),a.hash&&"#"!==a.hash.charAt(0)&&(a.hash="#"+a.hash),void 0!==e&&void 0===a.state&&(a.state=e));try{a.pathname=decodeURI(a.pathname)}catch(r){throw r instanceof URIError?new URIError('Pathname "'+a.pathname+'" could not be decoded. This is likely caused by an invalid percent-encoding.'):r}var o;return a.key=t,n?a.pathname?"/"!==a.pathname.charAt(0)&&(a.pathname=((r,e="")=>{let t,n=e&&e.split("/")||[],a=0;const o=r&&r.split("/")||[],s=r&&p(r),i=e&&p(e),l=s||i;if(r&&p(r)?n=o:o.length&&(n.pop(),n=n.concat(o)),!n.length)return"/";if(n.length){const r=n[n.length-1];t="."===r||".."===r||""===r}else t=!1;for(let r=n.length;r>=0;r--){const e=n[r];"."===e?h(n,r):".."===e?(h(n,r),a++):a&&(h(n,r),a--)}if(!l)for(;a--;a)n.unshift("..");!l||""===n[0]||n[0]&&p(n[0])||n.unshift("");let c=n.join("/");return t&&"/"!==c.substr(-1)&&(c+="/"),c})(a.pathname,n.pathname)):a.pathname=n.pathname:a.pathname||(a.pathname="/"),a.query=(o=a.search||"")?(/^[?#]/.test(o)?o.slice(1):o).split("&").reduce((r,e)=>{let[t,n]=e.split("=");return r[t]=n?decodeURIComponent(n.replace(/\+/g," ")):"",r},{}):{},a};let E=0;const x={},R=(r,e={})=>{"string"==typeof e&&(e={path:e});const{path:t="/",exact:n=!1,strict:a=!1}=e,{re:s,keys:i}=((r,e)=>{const t=`${e.end}${e.strict}`,n=x[t]||(x[t]={}),a=JSON.stringify(r);if(n[a])return n[a];const s=[],i={re:o(r,s,e),keys:s};return E<1e4&&(n[a]=i,E+=1),i})(t,{end:n,strict:a}),l=s.exec(r);if(!l)return null;const[c,...u]=l,f=r===c;return n&&!f?null:{path:t,url:"/"===t&&""===c?"/":c,isExact:f,params:i.reduce((r,e,t)=>(r[e.name]=u[t],r),{})}},m=(r,e)=>null==r&&null==e||null!=e&&r&&e&&r.path===e.path&&r.url===e.url&&v(r.params,e.params),$=(r,e,t)=>t(r.confirm(e)),O=r=>r.metaKey||r.altKey||r.ctrlKey||r.shiftKey,_=r=>{const e=r.navigator.userAgent;return(-1===e.indexOf("Android 2.")&&-1===e.indexOf("Android 4.0")||-1===e.indexOf("Mobile Safari")||-1!==e.indexOf("Chrome")||-1!==e.indexOf("Windows Phone"))&&r.history&&"pushState"in r.history},b=r=>-1===r.userAgent.indexOf("Trident"),w=r=>-1===r.userAgent.indexOf("Firefox"),A=(r,e)=>void 0===e.state&&-1===r.userAgent.indexOf("CriOS"),j=(r,e)=>{const t=r[e],n="__storage_test__";try{return t.setItem(n,n),t.removeItem(n),!0}catch(r){return r instanceof DOMException&&(22===r.code||1014===r.code||"QuotaExceededError"===r.name||"NS_ERROR_DOM_QUOTA_REACHED"===r.name)&&0!==t.length}};export{m as a,_ as b,b as c,l as d,c as e,y as f,d as g,s as h,i,f as j,$ as k,A as l,R as m,w as n,u as o,g as p,O as q,j as s}
================================================
FILE: screenshot/compare/build/p-b4cc611c.entry.js
================================================
import{r as t,g as e}from"./p-fbbae598.js";import{A as s}from"./p-e2efe0df.js";class i{constructor(e){t(this,e),this.titleSuffix="",this.pageTitle=""}updateDocumentTitle(){const t=this.el;t.ownerDocument&&(t.ownerDocument.title=`${this.pageTitle}${this.titleSuffix||""}`)}componentWillLoad(){this.updateDocumentTitle()}get el(){return e(this)}static get watchers(){return{pageTitle:["updateDocumentTitle"]}}}s.injectProps(i,["titleSuffix"]);export{i as stencil_route_title}
================================================
FILE: screenshot/compare/build/p-d1bf53f5.entry.js
================================================
import{r as t,h as i,g as s}from"./p-fbbae598.js";import{A as h}from"./p-e2efe0df.js";import{m as a,q as e}from"./p-9b6a9315.js";class r{constructor(i){t(this,i),this.unsubscribe=()=>{},this.activeClass="link-active",this.exact=!1,this.strict=!0,this.custom="a",this.match=null}componentWillLoad(){this.computeMatch()}computeMatch(){this.location&&(this.match=a(this.location.pathname,{path:this.urlMatch||this.url,exact:this.exact,strict:this.strict}))}handleClick(t){var i,s;if(!e(t)&&this.history&&this.url&&this.root)return t.preventDefault(),this.history.push((s=this.root,"/"==(i=this.url).charAt(0)&&"/"==s.charAt(s.length-1)?s.slice(0,s.length-1)+i:s+i))}render(){let t={class:{[this.activeClass]:null!==this.match},onClick:this.handleClick.bind(this)};return this.anchorClass&&(t.class[this.anchorClass]=!0),"a"===this.custom&&(t=Object.assign({},t,{href:this.url,title:this.anchorTitle,role:this.anchorRole,tabindex:this.anchorTabIndex,"aria-haspopup":this.ariaHaspopup,id:this.anchorId,"aria-posinset":this.ariaPosinset,"aria-setsize":this.ariaSetsize,"aria-label":this.ariaLabel})),i(this.custom,Object.assign({},t),i("slot",null))}get el(){return s(this)}static get watchers(){return{location:["computeMatch"]}}}h.injectProps(r,["history","location","root"]);export{r as stencil_route_link}
================================================
FILE: screenshot/compare/build/p-e2efe0df.js
================================================
import{h as t}from"./p-fbbae598.js";const e=(()=>{let e=new Map,r={historyType:"browser",location:{pathname:"",query:{},key:""},titleSuffix:"",root:"/",routeViewsUpdated:()=>{}};const o=(t,e)=>{Array.isArray(t)?[...t].forEach(t=>{e[t]=r[t]}):e[t]=Object.assign({},r)},s=(t,r)=>(e.has(t)||(e.set(t,r),o(r,t)),()=>{e.has(t)&&e.delete(t)});return{Provider:({state:t},s)=>(r=t,e.forEach(o),s),Consumer:(e,r)=>((e,r)=>t("context-consumer",{subscribe:e,renderer:r}))(s,r[0]),injectProps:(t,r)=>{const o=t.prototype,n=o.connectedCallback,i=o.disconnectedCallback;o.connectedCallback=function(){if(s(this,r),n)return n.call(this)},o.disconnectedCallback=function(){e.delete(this),i&&i.call(this)}}}})();export{e as A}
================================================
FILE: screenshot/compare/build/p-e8ca6d97.entry.js
================================================
import{r as t,g as r}from"./p-fbbae598.js";import{A as s}from"./p-e2efe0df.js";class i{constructor(r){t(this,r)}componentWillLoad(){if(this.history&&this.root&&this.url)return this.history.replace((r=this.root,"/"==(t=this.url).charAt(0)&&"/"==r.charAt(r.length-1)?r.slice(0,r.length-1)+t:r+t));var t,r}get el(){return r(this)}}s.injectProps(i,["history","root"]);export{i as stencil_router_redirect}
================================================
FILE: screenshot/compare/build/p-ec2f13e0.entry.js
================================================
import{r as t,h as e}from"./p-fbbae598.js";class n{constructor(e){t(this,e),this.content=""}componentWillLoad(){if(null!=this.documentLocation)return this.fetchNewContent(this.documentLocation)}fetchNewContent(t){return fetch(t).then(t=>t.text()).then(t=>{this.content=t})}render(){return e("div",{innerHTML:this.content})}static get watchers(){return{documentLocation:["fetchNewContent"]}}}export{n as stencil_async_content}
================================================
FILE: screenshot/compare/build/p-f0b99977.entry.js
================================================
import{r as t,g as s}from"./p-fbbae598.js";class e{constructor(s){t(this,s),this.context={},this.renderer=()=>null}connectedCallback(){null!=this.subscribe&&(this.unsubscribe=this.subscribe(this.el,"context"))}disconnectedCallback(){null!=this.unsubscribe&&this.unsubscribe()}render(){return this.renderer(Object.assign({},this.context))}get el(){return s(this)}}export{e as context_consumer}
================================================
FILE: screenshot/compare/build/p-f4745c2f.entry.js
================================================
import{r as t,d as s,h as i,g as e}from"./p-fbbae598.js";import{s as n}from"./p-081b0641.js";const h={threshold:.1,includeAA:!1,alpha:.1,aaColor:[255,255,0],diffColor:[255,0,0],diffColorAlt:null,diffMask:!1};function o(t){return ArrayBuffer.isView(t)&&1===t.constructor.BYTES_PER_ELEMENT}function r(t,s,i,e,n,h){const o=Math.max(s-1,0),r=Math.max(i-1,0),c=Math.min(s+1,e-1),d=Math.min(i+1,n-1),f=4*(i*e+s);let u,p,m,g,w=s===o||s===c||i===r||i===d?1:0,y=0,v=0;for(let n=o;n<=c;n++)for(let h=r;h<=d;h++){if(n===s&&h===i)continue;const o=l(t,t,f,4*(h*e+n),!0);if(0===o){if(w++,w>2)return!1}else ov&&(v=o,m=n,g=h)}return 0!==y&&0!==v&&(a(t,u,p,e,n)&&a(h,u,p,e,n)||a(t,m,g,e,n)&&a(h,m,g,e,n))}function a(t,s,i,e,n){const h=Math.max(s-1,0),o=Math.max(i-1,0),r=Math.min(s+1,e-1),a=Math.min(i+1,n-1),l=4*(i*e+s);let c=s===h||s===r||i===o||i===a?1:0;for(let n=h;n<=r;n++)for(let h=o;h<=a;h++){if(n===s&&h===i)continue;const o=4*(h*e+n);if(t[l]===t[o]&&t[l+1]===t[o+1]&&t[l+2]===t[o+2]&&t[l+3]===t[o+3]&&c++,c>2)return!0}return!1}function l(t,s,i,e,n){let h=t[i+0],o=t[i+1],r=t[i+2],a=t[i+3],l=s[e+0],p=s[e+1],m=s[e+2],g=s[e+3];if(a===g&&h===l&&o===p&&r===m)return 0;a<255&&(a/=255,h=u(h,a),o=u(o,a),r=u(r,a)),g<255&&(g/=255,l=u(l,g),p=u(p,g),m=u(m,g));const w=c(h,o,r),y=c(l,p,m),v=w-y;if(n)return v;const b=d(h,o,r)-d(l,p,m),x=f(h,o,r)-f(l,p,m),M=.5053*v*v+.299*b*b+.1957*x*x;return w>y?-M:M}function c(t,s,i){return.29889531*t+.58662247*s+.11448223*i}function d(t,s,i){return.59597799*t-.2741761*s-.32180189*i}function f(t,s,i){return.21147017*t-.52261711*s+.31114694*i}function u(t,s){return 255+(t-255)*s}function p(t,s,i,e,n){t[s+0]=i,t[s+1]=e,t[s+2]=n,t[s+3]=255}function m(t,s,i,e){const n=u(c(t[s+0],t[s+1],t[s+2]),i*t[s+3]/255);p(e,s,n,n,n)}function g(t,s,i){if(y.has(s))return void i(y.get(s));if(w.has(s))return void w.get(s).push(i);w.set(s,[i]);const e=document.createElement("script");e.src=`${t}screenshot_${s}.js`,document.head.appendChild(e)}window.loadScreenshot=(t,s)=>{const i=w.get(t);i&&(i.forEach(t=>t(s)),w.delete(t)),y.set(t,s)};const w=new Map,y=new Map;class v{constructor(i){t(this,i),this.imageASrc=null,this.imageBSrc=null,this.imageAClass="is-loading",this.imageBClass="is-loading",this.canvasClass="is-loading",this.imagesLoaded=new Set,this.isImageALoaded=!1,this.isImageBLoaded=!1,this.isMismatchInitialized=!1,this.hasCalculatedMismatch=!1,this.compareLoaded=s(this,"compareLoaded",7)}componentWillLoad(){this.loadScreenshots()}componentWillUpdate(){this.loadScreenshots()}loadScreenshots(){if(this.show&&this.diff.hasIntersected)return this.diff.identical?(this.imageASrc=this.imagesUrl+this.diff.imageA,this.isImageALoaded=!0,this.imageAClass="has-loaded",this.imageBSrc=this.imagesUrl+this.diff.imageB,this.isImageBLoaded=!0,void(this.imageBClass="has-loaded")):void(this.isMismatchInitialized||(this.isMismatchInitialized=!0,null!=this.jsonpUrl?(null!=this.diff.imageA&&g(this.jsonpUrl,this.diff.imageA,t=>{this.imageASrc=t}),null!=this.diff.imageB&&g(this.jsonpUrl,this.diff.imageB,t=>{this.imageBSrc=t})):(this.imageASrc=this.imagesUrl+this.diff.imageA,this.imageBSrc=this.imagesUrl+this.diff.imageB)))}async compareImages(){const t=this.diff;this.isImageALoaded&&this.isImageBLoaded&&!this.hasCalculatedMismatch&&t.comparable&&(this.hasCalculatedMismatch=!0,t.mismatchedPixels=await function(t,s,i,e,n,a){let c=-1;try{const d=document.createElement("canvas");d.width=e,d.height=n;const f=document.createElement("canvas");f.width=e,f.height=n;const u=d.getContext("2d");u.drawImage(t,0,0);const g=f.getContext("2d");g.drawImage(s,0,0);const w=document.createElement("canvas").getContext("2d");w.drawImage(t,0,0),w.getImageData(0,0,e,n);const y=u.getImageData(0,0,e,n).data,v=g.getImageData(0,0,e,n).data,b=i.getContext("2d"),x=b.createImageData(e,d.height);c=function(t,s,i,e,n,a){if(!o(t)||!o(s)||i&&!o(i))throw new Error("Image data: Uint8Array, Uint8ClampedArray or Buffer expected.");if(t.length!==s.length||i&&i.length!==t.length)throw new Error("Image sizes do not match.");if(t.length!==e*n*4)throw new Error("Image data size does not match width/height.");a=Object.assign({},h,a);const c=e*n,d=new Uint32Array(t.buffer,t.byteOffset,c),f=new Uint32Array(s.buffer,s.byteOffset,c);let u=!0;for(let t=0;tg?a.includeAA||!r(t,o,h,e,n,s)&&!r(s,o,h,e,n,t)?(i&&p(i,c,...d<0&&a.diffColorAlt||a.diffColor),w++):i&&!a.diffMask&&p(i,c,...a.aaColor):i&&(a.diffMask||m(t,c,a.alpha,i))}return w}(y,v,x.data,e,n,{threshold:a}),b.putImageData(x,0,0)}catch(t){console.error(t)}return c}(this.imageA,this.imageB,this.canvas,Math.round(t.width*t.deviceScaleFactor),Math.round(t.height*t.deviceScaleFactor),t.threshold),this.canvasClass="has-loaded",n(t.imageA,t.imageB,t.mismatchedPixels,t.threshold),this.compareLoaded.emit(t))}render(){const t=this.diff,s={width:t.width+"px",height:t.height+"px"};return[i("compare-cell",null,null!=t.imageA?i("a",{href:this.imagesUrl+t.imageA,target:"_blank"},i("img",{src:this.imageASrc,class:this.imageAClass,style:s,onLoad:this.diff.identical?null:()=>{this.isImageALoaded=!0,this.imageAClass="has-loaded",this.compareImages()},ref:t=>this.imageA=t})):i("img",{style:s,class:"is-loading"})),i("compare-cell",null,null!=t.imageB?i("a",{href:this.imagesUrl+t.imageB,target:"_blank"},i("img",{src:this.imageBSrc,class:this.imageBClass,style:s,onLoad:this.diff.identical?null:()=>{this.isImageBLoaded=!0,this.imageBClass="has-loaded",this.compareImages()},ref:t=>this.imageB=t})):i("img",{style:s,class:"is-loading"})),i("compare-cell",null,this.diff.identical?i("img",{style:s,src:this.imageASrc}):i("canvas",{width:Math.round(t.width*t.deviceScaleFactor),height:Math.round(t.height*t.deviceScaleFactor),class:this.canvasClass,style:s,hidden:!t.comparable,ref:t=>this.canvas=t})),i("compare-cell",null,i("compare-analysis",{aId:this.aId,bId:this.bId,mismatchedPixels:this.diff.mismatchedPixels,diff:this.diff}))]}get elm(){return e(this)}}v.style="compare-row img,compare-row canvas{display:block;box-shadow:var(--screenshot-box-shadow);border-radius:var(--screenshot-border-radius)}compare-row a{display:block}.is-loading{visibility:hidden}";class b{constructor(s){t(this,s)}render(){if(!this.a||!this.b||!this.diffs)return;let t=0;this.diffs.forEach(s=>{s.width>t&&(t=s.width)}),t-=6;const s={width:t+"px"};return[i("th-cell",null,i("div",{style:s},i("a",{href:this.a.url,target:"_blank"},this.a.message))),i("th-cell",null,i("div",{style:s},i("a",{href:this.b.url,target:"_blank"},this.b.message))),i("th-cell",null,i("div",{style:s},i("a",{href:`https://github.com/ionic-team/ionic/compare/${this.a.id}...${this.b.id}`,target:"_blank"},"Compare: ",this.a.id," - ",this.b.id))),i("th-cell",{class:"analysis"},i("div",null,"Analysis"))]}}b.style=":host{display:flex}th-cell{display:block;flex:1;font-weight:500;font-size:12px}th-cell div{padding-left:12px;padding-right:12px;overflow:hidden;white-space:nowrap;text-overflow:ellipsis}th-cell a{color:var(--font-color);text-decoration:none}th-cell a:hover{color:var(--analysis-data-color);text-decoration:underline}.analysis div{width:262px}";export{v as compare_row,b as compare_thead}
================================================
FILE: screenshot/compare/build/p-fbbae598.js
================================================
let e,t,n,l=!1,o=!1,s=!1,r=0,i=!1;const c="undefined"!=typeof window?window:{},a=c.document||{head:{}},f={t:0,l:"",jmp:e=>e(),raf:e=>requestAnimationFrame(e),ael:(e,t,n,l)=>e.addEventListener(t,n,l),rel:(e,t,n,l)=>e.removeEventListener(t,n,l)},u=e=>Promise.resolve(e),d=(()=>{try{return new CSSStyleSheet,!0}catch(e){}return!1})(),p={},$=(e,t,n)=>{n&&n.map(([n,l,o])=>{const s=e,r=m(t,o),i=h(n);f.ael(s,l,r,i),(t.o=t.o||[]).push(()=>f.rel(s,l,r,i))})},m=(e,t)=>n=>{256&e.t?e.s[t](n):(e.i=e.i||[]).push([t,n])},h=e=>0!=(2&e),y="http://www.w3.org/1999/xlink",b=new WeakMap,w=e=>"sc-"+e.u,k={},v=e=>"object"==(e=typeof e)||"function"===e,g=(e,t,...n)=>{let l=null,o=null,s=null,r=!1,i=!1,c=[];const a=t=>{for(let n=0;ne[t]).join(" "))}}if("function"==typeof e)return e(null===t?{}:t,c,M);const f=S(e,null);return f.$=t,c.length>0&&(f.m=c),f.h=o,f.k=s,f},S=(e,t)=>({t:0,v:e,p:t,g:null,m:null,$:null,h:null,k:null}),j={},M={forEach:(e,t)=>e.map(U).forEach(t),map:(e,t)=>e.map(U).map(t).map(C)},U=e=>({vattrs:e.$,vchildren:e.m,vkey:e.h,vname:e.k,vtag:e.v,vtext:e.p}),C=e=>{const t=S(e.vtag,e.vtext);return t.$=e.vattrs,t.m=e.vchildren,t.h=e.vkey,t.k=e.vname,t},R=(e,t,n,l,o,s)=>{if(n!==l){let r=de(e,t),i=t.toLowerCase();if("class"===t){const t=e.classList,o=L(n),s=L(l);t.remove(...o.filter(e=>e&&!s.includes(e))),t.add(...s.filter(e=>e&&!o.includes(e)))}else if("style"===t){for(const t in n)l&&null!=l[t]||(t.includes("-")?e.style.removeProperty(t):e.style[t]="");for(const t in l)n&&l[t]===n[t]||(t.includes("-")?e.style.setProperty(t,l[t]):e.style[t]=l[t])}else if("key"===t);else if("ref"===t)l&&l(e);else if(r||"o"!==t[0]||"n"!==t[1]){const c=v(l);if((r||c&&null!==l)&&!o)try{if(e.tagName.includes("-"))e[t]=l;else{let o=null==l?"":l;"list"===t?r=!1:null!=n&&e[t]==o||(e[t]=o)}}catch(e){}let a=!1;i!==(i=i.replace(/^xlink\:?/,""))&&(t=i,a=!0),null==l||!1===l?a?e.removeAttributeNS(y,t):e.removeAttribute(t):(!r||4&s||o)&&!c&&(l=!0===l?"":l,a?e.setAttributeNS(y,t,l):e.setAttribute(t,l))}else t="-"===t[2]?t.slice(3):de(c,i)?i.slice(2):i[2]+t.slice(3),n&&f.rel(e,t,n,!1),l&&f.ael(e,t,l,!1)}},x=/\s/,L=e=>e?e.split(x):[],O=(e,t,n,l)=>{const o=11===t.g.nodeType&&t.g.host?t.g.host:t.g,s=e&&e.$||k,r=t.$||k;for(l in s)l in r||R(o,l,s[l],void 0,n,t.t);for(l in r)R(o,l,s[l],r[l],n,t.t)},P=(o,r,i,c)=>{let f,u,d,p=r.m[i],$=0;if(l||(s=!0,"slot"===p.v&&(e&&c.classList.add(e+"-s"),p.t|=p.m?2:1)),null!==p.p)f=p.g=a.createTextNode(p.p);else if(1&p.t)f=p.g=a.createTextNode("");else if(f=p.g=a.createElement(2&p.t?"slot-fb":p.v),O(null,p,!1),null!=e&&f["s-si"]!==e&&f.classList.add(f["s-si"]=e),p.m)for($=0;${f.t|=1;const l=e.childNodes;for(let e=l.length-1;e>=0;e--){const o=l[e];o["s-hn"]!==n&&o["s-ol"]&&(A(o).insertBefore(o,q(o)),o["s-ol"].remove(),o["s-ol"]=void 0,s=!0),t&&T(o,t)}f.t&=-2},E=(e,t,l,o,s,r)=>{let i,c=e["s-cr"]&&e["s-cr"].parentNode||e;for(c.shadowRoot&&c.tagName===n&&(c=c.shadowRoot);s<=r;++s)o[s]&&(i=P(null,l,s,e),i&&(o[s].g=i,c.insertBefore(i,q(t))))},W=(e,t,n,l,s)=>{for(;t<=n;++t)(l=e[t])&&(s=l.g,z(l),o=!0,s["s-ol"]?s["s-ol"].remove():T(s,!0),s.remove())},D=(e,t)=>e.v===t.v&&("slot"===e.v?e.k===t.k:e.h===t.h),q=e=>e&&e["s-ol"]||e,A=e=>(e["s-ol"]?e["s-ol"]:e).parentNode,F=(e,t)=>{const n=t.g=e.g,l=e.m,o=t.m,s=t.p;let r;null===s?("slot"===t.v||O(e,t,!1),null!==l&&null!==o?((e,t,n,l)=>{let o,s,r=0,i=0,c=0,a=0,f=t.length-1,u=t[0],d=t[f],p=l.length-1,$=l[0],m=l[p];for(;r<=f&&i<=p;)if(null==u)u=t[++r];else if(null==d)d=t[--f];else if(null==$)$=l[++i];else if(null==m)m=l[--p];else if(D(u,$))F(u,$),u=t[++r],$=l[++i];else if(D(d,m))F(d,m),d=t[--f],m=l[--p];else if(D(u,m))"slot"!==u.v&&"slot"!==m.v||T(u.g.parentNode,!1),F(u,m),e.insertBefore(u.g,d.g.nextSibling),u=t[++r],m=l[--p];else if(D(d,$))"slot"!==u.v&&"slot"!==m.v||T(d.g.parentNode,!1),F(d,$),e.insertBefore(d.g,u.g),d=t[--f],$=l[++i];else{for(c=-1,a=r;a<=f;++a)if(t[a]&&null!==t[a].h&&t[a].h===$.h){c=a;break}c>=0?(s=t[c],s.v!==$.v?o=P(t&&t[i],n,c,e):(F(s,$),t[c]=void 0,o=s.g),$=l[++i]):(o=P(t&&t[i],n,i,e),$=l[++i]),o&&A(u.g).insertBefore(o,q(u.g))}r>f?E(e,null==l[p+1]?null:l[p+1].g,n,l,i,p):i>p&&W(t,r,f)})(n,l,t,o):null!==o?(null!==e.p&&(n.textContent=""),E(n,null,t,o,0,o.length-1)):null!==l&&W(l,0,l.length-1)):(r=n["s-cr"])?r.parentNode.textContent=s:e.p!==s&&(n.data=s)},N=e=>{let t,n,l,o,s,r,i=e.childNodes;for(n=0,l=i.length;n{let t,n,l,s,r,i,c=0,a=e.childNodes,f=a.length;for(;c=0;i--)n=l[i],n["s-cn"]||n["s-nr"]||n["s-hn"]===t["s-hn"]||(_(n,s)?(r=H.find(e=>e.S===n),o=!0,n["s-sn"]=n["s-sn"]||s,r?r.j=t:H.push({j:t,S:n}),n["s-sr"]&&H.map(e=>{_(e.S,n["s-sn"])&&(r=H.find(e=>e.S===n),r&&!e.j&&(e.j=r.j))})):H.some(e=>e.S===n)||H.push({S:n}));1===t.nodeType&&V(t)}},_=(e,t)=>1===e.nodeType?null===e.getAttribute("slot")&&""===t||e.getAttribute("slot")===t:e["s-sn"]===t||""===t,z=e=>{e.$&&e.$.ref&&e.$.ref(null),e.m&&e.m.map(z)},B=e=>ae(e).M,G=(e,t,n)=>{const l=B(e);return{emit:e=>I(l,t,{bubbles:!!(4&n),composed:!!(2&n),cancelable:!!(1&n),detail:e})}},I=(e,t,n)=>{const l=new CustomEvent(t,n);return e.dispatchEvent(l),l},J=(e,t)=>{t&&!e.U&&t["s-p"]&&t["s-p"].push(new Promise(t=>e.U=t))},K=(e,t)=>{if(e.t|=16,!(4&e.t))return J(e,e.C),Me(()=>Q(e,t));e.t|=512},Q=(e,t)=>{const n=e.s;let l;return t?(e.t|=256,e.i&&(e.i.map(([e,t])=>te(n,e,t)),e.i=null),l=te(n,"componentWillLoad")):l=te(n,"componentWillUpdate"),ne(l,()=>X(e,n,t))},X=(r,i,c)=>{const u=r.M,d=u["s-rc"];c&&(e=>{const t=e.R,n=e.M,l=t.t,o=((e,t)=>{let n=w(t),l=he.get(n);if(e=11===e.nodeType?e:a,l)if("string"==typeof l){let t,o=b.get(e=e.head||e);o||b.set(e,o=new Set),o.has(n)||(t=a.createElement("style"),t.innerHTML=l,e.insertBefore(t,e.querySelector("link")),o&&o.add(n))}else e.adoptedStyleSheets.includes(l)||(e.adoptedStyleSheets=[...e.adoptedStyleSheets,l]);return n})(n.shadowRoot?n.shadowRoot:n.getRootNode(),t);10&l&&(n["s-sc"]=o,n.classList.add(o+"-h"))})(r),((r,i)=>{const c=r.M,u=r.R,d=r.L||S(null,null),p=(e=>e&&e.v===j)(i)?i:g(null,null,i);if(n=c.tagName,u.O&&(p.$=p.$||{},u.O.map(([e,t])=>p.$[t]=c[e])),p.v=null,p.t|=4,r.L=p,p.g=d.g=c.shadowRoot||c,e=c["s-sc"],t=c["s-cr"],l=0!=(1&u.t),o=!1,F(d,p),f.t|=1,s){let e,t,n,l,o,s;V(p.g);let r=0;for(;re()),u["s-rc"]=void 0);{const e=u["s-p"],t=()=>Z(r);0===e.length?t():(Promise.all(e).then(t),r.t|=4,e.length=0)}},Y=(e,t)=>{try{t=t.render&&t.render(),e.t&=-17,e.t|=2}catch(e){pe(e)}return t},Z=e=>{const t=e.M,n=e.s,l=e.C;64&e.t?te(n,"componentDidUpdate"):(e.t|=64,le(t),te(n,"componentDidLoad"),e.P(t),l||ee()),e.U&&(e.U(),e.U=void 0),512&e.t&&Se(()=>K(e,!1)),e.t&=-517},ee=()=>{le(a.documentElement),f.t|=2,Se(()=>I(c,"appload",{detail:{namespace:"app"}}))},te=(e,t,n)=>{if(e&&e[t])try{return e[t](n)}catch(e){pe(e)}},ne=(e,t)=>e&&e.then?e.then(t):t(),le=e=>e.classList.add("hydrated"),oe=(e,t,n)=>{if(t.T){e.watchers&&(t.W=e.watchers);const l=Object.entries(t.T),o=e.prototype;if(l.map(([e,[l]])=>{(31&l||2&n&&32&l)&&Object.defineProperty(o,e,{get(){return((e,t)=>ae(this).D.get(t))(0,e)},set(n){((e,t,n,l)=>{const o=ae(this),s=o.D.get(t),r=o.t,i=o.s;if(n=((e,t)=>null==e||v(e)?e:4&t?"false"!==e&&(""===e||!!e):2&t?parseFloat(e):1&t?e+"":e)(n,l.T[t][0]),!(8&r&&void 0!==s||n===s)&&(o.D.set(t,n),i)){if(l.W&&128&r){const e=l.W[t];e&&e.map(e=>{try{i[e](n,s,t)}catch(e){pe(e)}})}2==(18&r)&&K(o,!1)}})(0,e,n,t)},configurable:!0,enumerable:!0})}),1&n){const n=new Map;o.attributeChangedCallback=function(e,t,l){f.jmp(()=>{const t=n.get(e);this[t]=(null!==l||"boolean"!=typeof this[t])&&l})},e.observedAttributes=l.filter(([e,t])=>15&t[0]).map(([e,l])=>{const o=l[1]||e;return n.set(o,e),512&l[0]&&t.O.push([e,o]),o})}}return e},se=e=>{te(e,"connectedCallback")},re=(e,t={})=>{const n=[],l=t.exclude||[],o=c.customElements,s=a.head,r=s.querySelector("meta[charset]"),i=a.createElement("style"),u=[];let p,m=!0;Object.assign(f,t),f.l=new URL(t.resourcesUrl||"./",a.baseURI).href,t.syncQueue&&(f.t|=4),e.map(e=>e[1].map(t=>{const s={t:t[0],u:t[1],T:t[2],q:t[3]};s.T=t[2],s.q=t[3],s.O=[],s.W={};const r=s.u,i=class extends HTMLElement{constructor(e){super(e),ue(e=this,s),1&s.t&&e.attachShadow({mode:"open"})}connectedCallback(){p&&(clearTimeout(p),p=null),m?u.push(this):f.jmp(()=>(e=>{if(0==(1&f.t)){const t=ae(e),n=t.R,l=()=>{};if(1&t.t)$(e,t,n.q),se(t.s);else{t.t|=1,12&n.t&&(e=>{const t=e["s-cr"]=a.createComment("");t["s-cn"]=!0,e.insertBefore(t,e.firstChild)})(e);{let n=e;for(;n=n.parentNode||n.host;)if(n["s-p"]){J(t,t.C=n);break}}n.T&&Object.entries(n.T).map(([t,[n]])=>{if(31&n&&e.hasOwnProperty(t)){const n=e[t];delete e[t],e[t]=n}}),Se(()=>(async(e,t,n,l,o)=>{if(0==(32&t.t)){t.t|=32;{if((o=me(n)).then){const e=()=>{};o=await o,e()}o.isProxied||(n.W=o.watchers,oe(o,n,2),o.isProxied=!0);const e=()=>{};t.t|=8;try{new o(t)}catch(e){pe(e)}t.t&=-9,t.t|=128,e(),se(t.s)}const e=w(n);if(!he.has(e)&&o.style){const t=()=>{};((e,t,n)=>{let l=he.get(e);d&&n?(l=l||new CSSStyleSheet,l.replace(t)):l=t,he.set(e,l)})(e,o.style,!!(1&n.t)),t()}}const s=t.C,r=()=>K(t,!0);s&&s["s-rc"]?s["s-rc"].push(r):r()})(0,t,n))}l()}})(this))}disconnectedCallback(){f.jmp(()=>(()=>{if(0==(1&f.t)){const e=ae(this),t=e.s;e.o&&(e.o.map(e=>e()),e.o=void 0),te(t,"disconnectedCallback"),te(t,"componentDidUnload")}})())}forceUpdate(){(()=>{{const e=ae(this);e.M.isConnected&&2==(18&e.t)&&K(e,!1)}})()}componentOnReady(){return ae(this).A}};s.F=e[0],l.includes(r)||o.get(r)||(n.push(r),o.define(r,oe(i,s,1)))})),i.innerHTML=n+"{visibility:hidden}.hydrated{visibility:inherit}",i.setAttribute("data-styles",""),s.insertBefore(i,r?r.nextSibling:s.firstChild),m=!1,u.length?u.map(e=>e.connectedCallback()):f.jmp(()=>p=setTimeout(ee,30))},ie=(e,t)=>t in p?p[t]:"window"===t?c:"document"===t?a:"isServer"!==t&&"isPrerender"!==t&&("isClient"===t||("resourcesUrl"===t||"publicPath"===t?(()=>{const e=new URL(".",f.l);return e.origin!==c.location.origin?e.href:e.pathname})():"queue"===t?{write:Me,read:je,tick:{then:e=>Se(e)}}:void 0)),ce=new WeakMap,ae=e=>ce.get(e),fe=(e,t)=>ce.set(t.s=e,t),ue=(e,t)=>{const n={t:0,M:e,R:t,D:new Map};return n.A=new Promise(e=>n.P=e),e["s-p"]=[],e["s-rc"]=[],$(e,n,t.q),ce.set(e,n)},de=(e,t)=>t in e,pe=e=>console.error(e),$e=new Map,me=e=>{const t=e.u.replace(/-/g,"_"),n=e.F,l=$e.get(n);return l?l[t]:import(`./${n}.entry.js`).then(e=>($e.set(n,e),e[t]),pe)},he=new Map,ye=[],be=[],we=[],ke=(e,t)=>n=>{e.push(n),i||(i=!0,t&&4&f.t?Se(ge):f.raf(ge))},ve=(e,t)=>{let n=0,l=0;for(;n{r++,(e=>{for(let t=0;t0&&(we.push(...be),be.length=0),(i=ye.length+be.length+we.length>0)?f.raf(ge):r=0}},Se=e=>u().then(e),je=ke(ye,!1),Me=ke(be,!0),Ue=()=>u(),Ce=()=>{const e=import.meta.url,t={};return""!==e&&(t.resourcesUrl=new URL(".",e).href),u(t)};export{Ue as a,re as b,ie as c,G as d,B as g,g as h,Ce as p,fe as r}
================================================
FILE: screenshot/compare/host.config.json
================================================
{
"hosting": {
"headers": [
{
"source": "/build/p-*",
"headers": [
{
"key": "Cache-Control",
"value": "max-age=31556952, s-maxage=31556952, immutable"
}
]
}
]
}
}
================================================
FILE: screenshot/compare/index.html
================================================
Stencil Screenshot Visual Diff ) {
const opts = getOptions(process.cwd(), {
isProd: args.includes('--prod'),
isCI: args.includes('--ci'),
isWatch: args.includes('--watch'),
});
try {
if (args.includes('--release')) {
await release(rootDir, args);
return;
}
if (args.includes('--validate-build')) {
await validateBuild(rootDir);
return;
}
await buildAll(opts);
} catch (e) {
console.error(e);
process.exit(1);
}
}
export async function buildAll(opts: BuildOptions) {
await Promise.all([
buildCli(opts),
buildCompiler(opts),
buildDevServer(opts),
buildMockDoc(opts),
buildScreenshot(opts),
buildSysNode(opts),
buildTesting(opts),
buildInternal(opts),
]);
}
================================================
FILE: scripts/esbuild/cli.ts
================================================
import type { BuildOptions as ESBuildOptions } from 'esbuild';
import fs from 'fs-extra';
import { join } from 'path';
import { getBanner } from '../utils/banner';
import { BuildOptions } from '../utils/options';
import { writePkgJson } from '../utils/write-pkg-json';
import { externalNodeModules, getBaseEsbuildOptions, getEsbuildAliases, runBuilds } from './utils';
/**
* Runs esbuild to bundle the `cli` submodule
*
* @param opts build options
* @returns a promise for this bundle's build output
*/
export async function buildCli(opts: BuildOptions) {
// clear out rollup stuff
await fs.emptyDir(opts.output.cliDir);
const inputDir = join(opts.srcDir, 'cli');
const buildDir = join(opts.buildDir, 'cli');
const outputDir = opts.output.cliDir;
const esmFilename = 'index.js';
const cjsFilename = 'index.cjs';
const dtsFilename = 'index.d.ts';
const cliAliases = getEsbuildAliases();
// this isn't strictly necessary to alias - however, this minimizes cuts down the bundle size by ~70kb.
cliAliases['prompts'] = 'prompts/lib/index.js';
const external = [...externalNodeModules, '../testing/*'];
const cliEsbuildOptions = {
...getBaseEsbuildOptions(),
alias: cliAliases,
entryPoints: [join(inputDir, 'index.ts')],
external,
platform: 'node',
} satisfies ESBuildOptions;
// ESM build options
const esmOptions: ESBuildOptions = {
...cliEsbuildOptions,
outfile: join(outputDir, esmFilename),
format: 'esm',
banner: {
js: getBanner(opts, `Stencil CLI`, true),
},
};
// CommonJS build options
const cjsOptions: ESBuildOptions = {
...cliEsbuildOptions,
outfile: join(outputDir, cjsFilename),
platform: 'node',
format: 'cjs',
banner: {
js: getBanner(opts, `Stencil CLI (CommonJS)`, true),
},
};
// create public d.ts
let dts = await fs.readFile(join(buildDir, 'public.d.ts'), 'utf8');
dts = dts.replace('@stencil/core/internal', '../internal/index');
await fs.writeFile(join(opts.output.cliDir, dtsFilename), dts);
// copy config-flags.d.ts
let configDts = await fs.readFile(join(buildDir, 'config-flags.d.ts'), 'utf8');
configDts = configDts.replace('@stencil/core/declarations', '../internal/index');
await fs.writeFile(join(opts.output.cliDir, 'config-flags.d.ts'), configDts);
// write cli/package.json
writePkgJson(opts, opts.output.cliDir, {
name: '@stencil/core/cli',
description: 'Stencil CLI.',
main: cjsFilename,
module: esmFilename,
types: dtsFilename,
});
return runBuilds([esmOptions, cjsOptions], opts);
}
================================================
FILE: scripts/esbuild/compiler.ts
================================================
import type { BuildOptions as ESBuildOptions } from 'esbuild';
import { replace } from 'esbuild-plugin-replace';
import fs from 'fs-extra';
import { join } from 'path';
import { getBanner } from '../utils/banner';
import { BuildOptions, createReplaceData } from '../utils/options';
import { writePkgJson } from '../utils/write-pkg-json';
import { externalNodeModules, getBaseEsbuildOptions, getEsbuildAliases, runBuilds } from './utils';
import { bundleParse5 } from './utils/parse5';
import { bundleTerser } from './utils/terser';
import { bundleTypeScriptSource, tsCacheFilePath } from './utils/typescript-source';
export async function buildCompiler(opts: BuildOptions) {
const inputDir = join(opts.buildDir, 'compiler');
const srcDir = join(opts.srcDir, 'compiler');
const compilerFileName = 'stencil.js';
const compilerDtsName = compilerFileName.replace('.js', '.d.ts');
// clear out rollup stuff and ensure directory exists
await fs.emptyDir(opts.output.compilerDir);
// create public d.ts
let dts = await fs.readFile(join(inputDir, 'public.d.ts'), 'utf8');
dts = dts.replace('@stencil/core/internal', '../internal/index');
await fs.writeFile(join(opts.output.compilerDir, compilerDtsName), dts);
// write @stencil/core/compiler/package.json
writePkgJson(opts, opts.output.compilerDir, {
name: '@stencil/core/compiler',
description: 'Stencil Compiler.',
main: compilerFileName,
types: compilerDtsName,
});
// copy and edit compiler/sys/in-memory-fs.d.ts
let inMemoryFsDts = await fs.readFile(join(inputDir, 'sys', 'in-memory-fs.d.ts'), 'utf8');
inMemoryFsDts = inMemoryFsDts.replace('@stencil/core/internal', '../../internal/index');
await fs.ensureDir(join(opts.output.compilerDir, 'sys'));
await fs.writeFile(join(opts.output.compilerDir, 'sys', 'in-memory-fs.d.ts'), inMemoryFsDts);
// copy and edit compiler/transpile.d.ts
let transpileDts = await fs.readFile(join(inputDir, 'transpile.d.ts'), 'utf8');
transpileDts = transpileDts.replace('@stencil/core/internal', '../internal/index');
await fs.writeFile(join(opts.output.compilerDir, 'transpile.d.ts'), transpileDts);
const alias: Record = {
...getEsbuildAliases(),
glob: './sys/node/glob.js',
'@sys-api-node': '../sys/node/index.js',
};
const external = [
...externalNodeModules,
'../mock-doc/index.cjs',
'../sys/node/autoprefixer.js',
'../sys/node/index.js',
];
// get replace data, which replaces certain strings within the output with
// build-time constants.
//
// this setup was originally designed for use with the Rollup `replace`
// plugin, but there is an esbuild plugin which provides equivalent
// functionality
//
// note that the `bundleTypeScriptSource` function implicitly depends on
// `createReplaceData` being called before it
const replaceData = createReplaceData(opts);
// stuff to patch typescript before bundling
const tsPath = require.resolve('typescript');
await bundleTypeScriptSource(tsPath, opts);
const tsFilePath = tsCacheFilePath(opts);
alias['typescript'] = tsFilePath;
// same for terser
const [, terserPath] = await bundleTerser(opts);
alias['terser'] = terserPath;
// and parse5
const [, parse5path] = await bundleParse5(opts);
alias['parse5'] = parse5path;
const compilerEsbuildOptions: ESBuildOptions = {
...getBaseEsbuildOptions(),
banner: { js: getBanner(opts, 'Stencil Compiler', true) },
entryPoints: [join(srcDir, 'index.ts')],
platform: 'node',
external,
format: 'cjs',
alias,
plugins: [replace(replaceData)],
outfile: join(opts.output.compilerDir, compilerFileName),
// workaround for fdir https://github.com/thecodrr/fdir/issues/163
inject: [join(opts.bundleHelpersDir, 'import-meta-url.js')],
define: {
'import.meta.url': 'import_meta_url',
},
};
// copy typescript default lib dts files
const tsLibNames = await getTypeScriptDefaultLibNames(opts);
await Promise.all(tsLibNames.map((f) => fs.copy(join(opts.typescriptLibDir, f), join(opts.output.compilerDir, f))));
return runBuilds([compilerEsbuildOptions], opts);
}
/**
* Helper function that reads in the `lib.*.d.ts` files in the TypeScript lib/ directory on disk.
* @param opts the Stencil build options, which includes the location of the TypeScript lib/
* @returns all file names that match the `lib.*.d.ts` format
*/
async function getTypeScriptDefaultLibNames(opts: BuildOptions): Promise {
return (await fs.readdir(opts.typescriptLibDir)).filter((f) => f.startsWith('lib.') && f.endsWith('.d.ts'));
}
================================================
FILE: scripts/esbuild/dev-server.ts
================================================
import { builtinModules } from 'node:module';
import { join } from 'node:path';
import type { BuildOptions as ESBuildOptions, Plugin } from 'esbuild';
import { replace } from 'esbuild-plugin-replace';
import fs from 'fs-extra';
import ts from 'typescript';
import { getBanner } from '../utils/banner';
import { type BuildOptions, createReplaceData } from '../utils/options';
import { writePkgJson } from '../utils/write-pkg-json';
import { externalAlias, getBaseEsbuildOptions, getEsbuildAliases, getFirstOutputFile, runBuilds } from './utils';
import { createContentTypeData } from './utils/content-types';
const CONNECTOR_NAME = 'connector.html';
/**
* Runs esbuild to bundle the `dev-server` submodule
*
* @param opts build options
* @returns a promise for this bundle's build output
*/
export async function buildDevServer(opts: BuildOptions) {
// create dir of not existing already
await fs.ensureDir(opts.output.devServerDir);
// clear out rollup stuff
await fs.emptyDir(opts.output.devServerDir);
const inputDir = join(opts.buildDir, 'dev-server');
// create public d.ts
let dts = await fs.readFile(join(opts.buildDir, 'dev-server', 'index.d.ts'), 'utf8');
dts = dts.replace('../declarations', '../internal/index');
await fs.writeFile(join(opts.output.devServerDir, 'index.d.ts'), dts);
// write package.json
writePkgJson(opts, opts.output.devServerDir, {
name: '@stencil/core/dev-server',
description: 'Stencil Development Server which communicates with the Stencil Compiler.',
main: 'index.js',
types: 'index.d.ts',
});
// copy static files
await fs.copy(join(opts.srcDir, 'dev-server', 'static'), join(opts.output.devServerDir, 'static'));
// copy server-worker-thread.js
await fs.copy(
join(opts.srcDir, 'dev-server', 'server-worker-thread.js'),
join(opts.output.devServerDir, 'server-worker-thread.js'),
);
// copy template files
await fs.copy(join(opts.srcDir, 'dev-server', 'templates'), join(opts.output.devServerDir, 'templates'));
// open-in-editor's visualstudio.vbs file
const visualstudioVbsSrc = join(opts.nodeModulesDir, 'open-in-editor', 'lib', 'editors', 'visualstudio.vbs');
const visualstudioVbsDesc = join(opts.output.devServerDir, 'visualstudio.vbs');
await fs.copy(visualstudioVbsSrc, visualstudioVbsDesc);
// copy open's xdg-open file
const xdgOpenSrcPath = join(opts.nodeModulesDir, 'open', 'xdg-open');
const xdgOpenDestPath = join(opts.output.devServerDir, 'xdg-open');
await fs.copy(xdgOpenSrcPath, xdgOpenDestPath);
const external = [...builtinModules];
const devServerAliases = {
...getEsbuildAliases(),
glob: '../../sys/node/glob.js',
'@stencil/core/mock-doc': '../../mock-doc/index.cjs',
};
const devServerIndexEsbuildOptions = {
...getBaseEsbuildOptions(),
alias: devServerAliases,
entryPoints: [join(inputDir, 'index.js')],
outfile: join(opts.output.devServerDir, 'index.js'),
external: ['@dev-server-process', ...external],
format: 'cjs',
platform: 'node',
write: false,
plugins: [serverProcessAliasPlugin(), replace(createReplaceData(opts))],
banner: {
js: getBanner(opts, `Stencil Dev Server`, true),
},
} satisfies ESBuildOptions;
const devServerProcessEsbuildOptions = {
...getBaseEsbuildOptions(),
alias: {
...devServerAliases,
glob: '../../sys/node/glob.js',
'@stencil/core/mock-doc': '../../mock-doc/index.cjs',
'@sys-api-node': '../sys/node/index.js',
},
entryPoints: [join(inputDir, 'server-process.js')],
outfile: join(opts.output.devServerDir, 'server-process.js'),
external: [...external, '../sys/node/index.js'],
format: 'cjs',
platform: 'node',
write: false,
plugins: [
esm2CJSPlugin(),
contentTypesPlugin(opts),
replace(createReplaceData(opts)),
externalAlias('graceful-fs', '../sys/node/graceful-fs.js'),
],
banner: {
js: getBanner(opts, `Stencil Dev Server Process`, true),
},
} satisfies ESBuildOptions;
const connectorAlias = {
glob: '../../sys/node/glob.js',
'@stencil/core/dev-server/client': join(inputDir, 'client', 'index.js'),
'@stencil/core/mock-doc': '../../mock-doc/index.cjs',
};
const connectorEsbuildOptions = {
...getBaseEsbuildOptions(),
alias: connectorAlias,
entryPoints: [join(inputDir, 'dev-server-client', 'index.js')],
outfile: join(opts.output.devServerDir, CONNECTOR_NAME),
format: 'cjs',
platform: 'node',
write: false,
plugins: [appErrorCssPlugin(opts), clientConnectorPlugin(opts), replace(createReplaceData(opts))],
} satisfies ESBuildOptions;
await fs.ensureDir(join(opts.output.devServerDir, 'client'));
// copy dev server client dts files
await fs.copy(join(opts.buildDir, 'dev-server', 'client'), join(opts.output.devServerDir, 'client'), {
filter: (src) => {
if (src.endsWith('.d.ts')) {
return true;
}
const stats = fs.statSync(src);
if (stats.isDirectory()) {
return true;
}
return false;
},
});
// write package.json
writePkgJson(opts, join(opts.output.devServerDir, 'client'), {
name: '@stencil/core/dev-server/client',
description: 'Stencil Dev Server Client.',
main: 'index.js',
types: 'index.d.ts',
});
const devServerClientEsbuildOptions = {
...getBaseEsbuildOptions(),
entryPoints: [join(opts.buildDir, 'dev-server', 'client', 'index.js')],
outfile: join(opts.output.devServerDir, 'client', 'index.js'),
format: 'esm',
platform: 'node',
plugins: [appErrorCssPlugin(opts), replace(createReplaceData(opts))],
banner: {
js: getBanner(opts, `Stencil Dev Server Client`, true),
},
} satisfies ESBuildOptions;
return runBuilds(
[
devServerIndexEsbuildOptions,
devServerProcessEsbuildOptions,
connectorEsbuildOptions,
devServerClientEsbuildOptions,
],
opts,
);
}
/**
* Load CSS files and export them as a string
* @param opts build options
* @returns an esbuild plugin
*/
function appErrorCssPlugin(opts: BuildOptions): Plugin {
return {
name: 'appErrorCss',
setup(build) {
build.onResolve({ filter: /app-error\.css$/ }, () => ({
path: join(opts.srcDir, 'dev-server', 'client', 'app-error.css'),
}));
build.onLoad({ filter: /app-error\.css$/ }, async (args) => {
const code = await fs.readFile(args.path, 'utf8');
const css = code.replace(/\n/g, ' ').trim();
const minified = css.replace(/ /g, ' ');
return { contents: `export default ${JSON.stringify(minified)};` };
});
},
};
}
/**
* Transform connector client script into a HTML file
* @param opts build options
* @returns an esbuild plugin
*/
function clientConnectorPlugin(opts: BuildOptions): Plugin {
return {
name: 'clientConnectorPlugin',
setup(build) {
build.onEnd(async (buildResult) => {
const bundle = buildResult.outputFiles?.find((b) => b.path.endsWith(CONNECTOR_NAME));
if (!bundle) {
throw "Couldn't find build result!";
}
let code = Buffer.from(bundle.contents).toString();
const tsResults = ts.transpileModule(code, {
compilerOptions: {
target: ts.ScriptTarget.ES5,
},
});
if (tsResults.diagnostics?.length) {
throw new Error(tsResults.diagnostics as any);
}
code = tsResults.outputText;
code = intro + code + outro;
if (opts.isProd) {
const { minify } = await import('terser');
const minifyResults = await minify(code, {
compress: { hoist_vars: true, hoist_funs: true, ecma: 5 },
format: { ecma: 5 },
});
if (minifyResults.code) {
code = minifyResults.code;
}
}
code = banner + code + footer;
code = code.replace(/__VERSION:STENCIL__/g, opts.version);
return fs.writeFile(bundle.path, code);
});
},
};
}
/**
* esbuild plugin to support alias of dynamic import. Transforming a path within a dynamic import
* does not seem to be supported yet.
* @see https://github.com/evanw/esbuild/issues/700
* @returns an esbuild plugin
*/
function serverProcessAliasPlugin(): Plugin {
return {
name: 'serverProcessAlias',
setup(build) {
build.onEnd(async (buildResult) => {
const bundle = getFirstOutputFile(buildResult);
let code = Buffer.from(bundle.contents).toString();
code = code.replace('await import("@dev-server-process")', '(await import("./server-process.js")).default');
return fs.writeFile(bundle.path, code);
});
},
};
}
/**
* The `open` NPM package is build as ESM module and uses ESM runtime features like `import.meta.url`.
* This plugin transforms this into CJS compliant code.
* @returns an esbuild plugin
*/
function esm2CJSPlugin(): Plugin {
return {
name: 'esm2CJS',
setup(build) {
build.onEnd(async (buildResult) => {
const bundle = getFirstOutputFile(buildResult);
let code = Buffer.from(bundle.contents).toString();
code = code.replace('import_meta.url', 'new (require("url").URL)("file:" + __filename).href');
return fs.writeFile(bundle.path, code);
});
},
};
}
/**
* Populates the `content-types-db.json` file with the content types of the `mime-db` package.
* @param opts build options
* @returns an esbuild plugin
*/
function contentTypesPlugin(opts: BuildOptions): Plugin {
return {
name: 'contentTypesPlugin',
setup(build) {
build.onLoad({ filter: /content-types-db\.json$/ }, async () => {
const contents = await createContentTypeData(opts);
return { contents };
});
},
};
}
const banner = `Stencil Dev Server Connector __VERSION:STENCIL__ ⚡
Stencil Dev Server Connector __VERSION:STENCIL__ ⚡
`;
================================================
FILE: scripts/esbuild/helpers/empty.js
================================================
module.exports = {};
================================================
FILE: scripts/esbuild/helpers/import-meta-url.js
================================================
export var import_meta_url = require('url').pathToFileURL(__filename);
================================================
FILE: scripts/esbuild/helpers/jest/jest-environment.js
================================================
const { getCreateJestPuppeteerEnvironment } = require('./index.js');
const createJestPuppeteerEnvironment = getCreateJestPuppeteerEnvironment();
module.exports = createJestPuppeteerEnvironment();
================================================
FILE: scripts/esbuild/helpers/jest/jest-preprocessor.js
================================================
const { getJestPreprocessor } = require('./index.js');
const jestPreprocessor = getJestPreprocessor();
module.exports = jestPreprocessor;
================================================
FILE: scripts/esbuild/helpers/jest/jest-preset.js
================================================
const { getJestPreset } = require('./index.js');
module.exports = getJestPreset();
================================================
FILE: scripts/esbuild/helpers/jest/jest-runner.js
================================================
const { getCreateJestTestRunner } = require('./index.js');
const createTestRunner = getCreateJestTestRunner();
module.exports = createTestRunner();
================================================
FILE: scripts/esbuild/helpers/jest/jest-setuptestframework.js
================================================
const { getJestSetupTestFramework } = require('./index.js');
const jestSetupTestFramework = getJestSetupTestFramework();
jestSetupTestFramework();
================================================
FILE: scripts/esbuild/helpers/lazy-require.js
================================================
// eslint-disable-next-line @typescript-eslint/no-unused-vars
function _lazyRequire(moduleId) {
return new Proxy(
{},
{
get(_target, propertyKey) {
const importedModule = require(moduleId);
return Reflect.get(importedModule, propertyKey);
},
set(_target, propertyKey, value) {
const importedModule = require(moduleId);
return Reflect.set(importedModule, propertyKey, value);
},
},
);
}
================================================
FILE: scripts/esbuild/helpers/path-is-absolute.js
================================================
import { isAbsolute } from 'path';
export default isAbsolute;
================================================
FILE: scripts/esbuild/internal-app-data.ts
================================================
import type { BuildOptions as ESBuildOptions } from 'esbuild';
import fs from 'fs-extra';
import { join } from 'path';
import { BuildOptions } from '../utils/options';
import { writePkgJson } from '../utils/write-pkg-json';
import { getBaseEsbuildOptions } from './utils';
/**
* Get an object containing ESbuild options to build the internal app data
* file. This function also performs relevant side-effects, like writing a
* `package.json` file to disk.
*
* @param opts build options
* @returns a Promise wrapping an array of ESbuild option objects
*/
export async function getInternalAppDataBundles(opts: BuildOptions): Promise {
const appDataBuildDir = join(opts.buildDir, 'app-data');
const appDataSrcDir = join(opts.srcDir, 'app-data');
const outputInternalAppDataDir = join(opts.output.internalDir, 'app-data');
await fs.emptyDir(outputInternalAppDataDir);
// copy @stencil/core/internal/app-data/index.d.ts
await fs.copyFile(join(appDataBuildDir, 'index.d.ts'), join(outputInternalAppDataDir, 'index.d.ts'));
// write @stencil/core/internal/app-data/package.json
writePkgJson(opts, outputInternalAppDataDir, {
name: '@stencil/core/internal/app-data',
description: 'Used for default app data and build conditionals within builds.',
main: 'index.cjs',
module: 'index.js',
types: 'index.d.ts',
sideEffects: false,
});
const appDataBaseOptions: ESBuildOptions = {
...getBaseEsbuildOptions(),
entryPoints: [join(appDataSrcDir, 'index.ts')],
platform: 'node',
};
const appDataESM: ESBuildOptions = {
...appDataBaseOptions,
format: 'esm',
outfile: join(outputInternalAppDataDir, 'index.js'),
};
const appDataCJS: ESBuildOptions = {
...appDataBaseOptions,
format: 'cjs',
outfile: join(outputInternalAppDataDir, 'index.cjs'),
};
return [appDataESM, appDataCJS];
}
================================================
FILE: scripts/esbuild/internal-app-globals.ts
================================================
import type { BuildOptions as ESBuildOptions } from 'esbuild';
import fs from 'fs-extra';
import { join } from 'path';
import { BuildOptions } from '../utils/options';
import { writePkgJson } from '../utils/write-pkg-json';
import { getBaseEsbuildOptions } from './utils';
/**
* Get an object containing ESbuild options to build the internal app globals
* file. This function also performs relevant side-effects, like writing a
* `package.json` file to disk.
*
* @param opts build options
* @returns a Promise wrapping an array of ESbuild option objects
*/
export async function getInternalAppGlobalsBundles(opts: BuildOptions): Promise {
const appGlobalsBuildDir = join(opts.buildDir, 'app-globals');
const appGlobalsSrcDir = join(opts.srcDir, 'app-globals');
const outputInternalAppDataDir = join(opts.output.internalDir, 'app-globals');
await fs.emptyDir(outputInternalAppDataDir);
// copy @stencil/core/internal/app-globals/index.d.ts
await fs.copyFile(join(appGlobalsBuildDir, 'index.d.ts'), join(outputInternalAppDataDir, 'index.d.ts'));
// write @stencil/core/internal/app-globals/package.json
writePkgJson(opts, outputInternalAppDataDir, {
name: '@stencil/core/internal/app-globals',
description: 'Used for default app globals.',
main: 'index.js',
module: 'index.js',
sideEffects: false,
});
const appGlobalsBaseOptions: ESBuildOptions = {
...getBaseEsbuildOptions(),
entryPoints: [join(appGlobalsSrcDir, 'index.ts')],
platform: 'node',
};
const appGlobalsESM: ESBuildOptions = {
...appGlobalsBaseOptions,
format: 'esm',
outfile: join(outputInternalAppDataDir, 'index.js'),
};
return [appGlobalsESM];
}
================================================
FILE: scripts/esbuild/internal-platform-client.ts
================================================
import type { BuildOptions as ESBuildOptions, Plugin } from 'esbuild';
import { replace } from 'esbuild-plugin-replace';
import fs from 'fs-extra';
import { glob } from 'glob';
import { join } from 'path';
import { getBanner } from '../utils/banner';
import { BuildOptions, createReplaceData } from '../utils/options';
import { writePkgJson } from '../utils/write-pkg-json';
import { externalAlias, externalNodeModules, getBaseEsbuildOptions, getEsbuildAliases } from './utils';
/**
* Create objects containing ESbuild options for the two bundles which need to
* be written to `internal/client`. This also performs relevant side-effects,
* like clearing out the directory and writing a `package.json` script to disk.
*
* @param opts build options
* @returns an array of ESBuild option objects
*/
export async function getInternalClientBundles(opts: BuildOptions): Promise {
const inputClientDir = join(opts.srcDir, 'client');
const outputInternalClientDir = join(opts.output.internalDir, 'client');
const outputInternalClientPolyfillsDir = join(outputInternalClientDir, 'polyfills');
await fs.emptyDir(outputInternalClientDir);
await fs.emptyDir(outputInternalClientPolyfillsDir);
await copyPolyfills(opts, outputInternalClientPolyfillsDir);
// write @stencil/core/internal/client/package.json
writePkgJson(opts, outputInternalClientDir, {
name: '@stencil/core/internal/client',
description:
'Stencil internal client platform to be imported by the Stencil Compiler and internal runtime. Breaking changes can and will happen at any time.',
exports: './index.js',
main: './index.js',
type: 'module',
sideEffects: false,
});
const internalClientAliases = getEsbuildAliases();
internalClientAliases['@platform'] = join(inputClientDir, 'index.ts');
const clientExternal = externalNodeModules;
const internalClientBundle: ESBuildOptions = {
...getBaseEsbuildOptions(),
entryPoints: [join(inputClientDir, 'index.ts')],
format: 'esm',
// we do 'write: false' here because we write the build to disk in our
// `findAndReplaceLoadModule` plugin below
write: false,
outfile: join(outputInternalClientDir, 'index.js'),
platform: 'node',
external: clientExternal,
alias: internalClientAliases,
banner: {
js: getBanner(opts, 'Stencil Client Platform'),
},
plugins: [
replace(createReplaceData(opts)),
externalAlias('@app-data', '@stencil/core/internal/app-data'),
externalAlias('@app-globals', '@stencil/core/internal/app-globals'),
externalAlias('@utils/shadow-css', './shadow-css.js'),
findAndReplaceLoadModule(),
],
};
const patchBrowserAliases = getEsbuildAliases();
const polyfills = await fs.readdir(join(opts.srcDir, 'client', 'polyfills'));
for (const polyFillFile of polyfills) {
patchBrowserAliases[`polyfills/${polyFillFile}`] = join(opts.srcDir, 'client', 'polyfills');
}
const patchBrowserExternal = [...externalNodeModules, '@stencil/core', '@stencil/core/mock-doc'];
const internalClientPatchBrowserBundle: ESBuildOptions = {
...getBaseEsbuildOptions(),
entryPoints: [join(inputClientDir, 'client-patch-browser.ts')],
format: 'esm',
outfile: join(outputInternalClientDir, 'patch-browser.js'),
platform: 'node',
external: patchBrowserExternal,
alias: patchBrowserAliases,
banner: {
js: getBanner(opts, 'Stencil Client Patch Browser'),
},
plugins: [
replace(createReplaceData(opts)),
externalAlias('@platform', '@stencil/core'),
externalAlias('@app-data', '@stencil/core/internal/app-data'),
externalAlias('@app-globals', '@stencil/core/internal/app-globals'),
],
};
return [internalClientBundle, internalClientPatchBrowserBundle];
}
/**
* We need to manually find-and-replace a bit of code in
* `client-load-module.ts` in order to prevent Esbuild from analyzing /
* transforming the input by ensuring it does not start with `"./"`. However
* some _other_ bundlers will _not_ work with such an import if it _lacks_ a
* leading `"./"`, so we thus we have to do a little dance where we manually
* replace it here after it's been run through Esbuild.
*
* @returns an Esbuild plugin
*/
export function findAndReplaceLoadModule(): Plugin {
return {
name: 'findAndReplaceLoadModule',
setup(build) {
build.onEnd(async (result) => {
for (const file of result.outputFiles!) {
const { path, text } = file;
await fs.writeFile(path, text.replace(/\${MODULE_IMPORT_PREFIX}/, './'));
}
});
},
};
}
async function copyPolyfills(opts: BuildOptions, outputInternalClientPolyfillsDir: string) {
const srcPolyfillsDir = join(opts.srcDir, 'client', 'polyfills');
const srcPolyfillFiles = glob.sync('*.js', { cwd: srcPolyfillsDir });
await Promise.all(
srcPolyfillFiles.map(async (fileName) => {
const src = join(srcPolyfillsDir, fileName);
const dest = join(outputInternalClientPolyfillsDir, fileName);
await fs.copyFile(src, dest);
}),
);
}
================================================
FILE: scripts/esbuild/internal-platform-hydrate.ts
================================================
import type { BuildOptions as ESBuildOptions } from 'esbuild';
import fs from 'fs-extra';
import { join } from 'path';
import { getBanner } from '../utils/banner';
import { bundleDts } from '../utils/bundle-dts';
import { BuildOptions } from '../utils/options';
import { writePkgJson } from '../utils/write-pkg-json';
import { externalAlias, externalNodeModules, getBaseEsbuildOptions, getEsbuildAliases } from './utils';
/**
* Create objects containing ESbuild options for the two bundles comprising
* the hydrate platform. This also performs relevant side-effects, like
* clearing out a directory and writing a `package.json` script to disk.
*
* @param opts build options
* @returns an array of ESBuild option objects
*/
export async function getInternalPlatformHydrateBundles(opts: BuildOptions): Promise {
const inputHydrateDir = join(opts.buildDir, 'hydrate');
const hydrateSrcDir = join(opts.srcDir, 'hydrate');
const outputInternalHydrateDir = join(opts.output.internalDir, 'hydrate');
await fs.emptyDir(outputInternalHydrateDir);
// write @stencil/core/internal/hydrate/package.json
writePkgJson(opts, outputInternalHydrateDir, {
name: '@stencil/core/internal/hydrate',
description:
'Stencil internal hydrate platform to be imported by the Stencil Compiler. Breaking changes can and will happen at any time.',
main: 'index.js',
});
await createHydrateRunnerDtsBundle(opts, inputHydrateDir, outputInternalHydrateDir);
const hydratePlatformInput = join(hydrateSrcDir, 'platform', 'index.js');
const external = externalNodeModules;
const internalHydrateAliases = getEsbuildAliases();
internalHydrateAliases['@platform'] = hydratePlatformInput;
const internalHydratePlatformBundle: ESBuildOptions = {
...getBaseEsbuildOptions(),
entryPoints: [hydratePlatformInput],
format: 'esm',
platform: 'node',
outfile: join(outputInternalHydrateDir, 'index.js'),
external,
alias: internalHydrateAliases,
banner: {
js: getBanner(opts, 'Stencil Hydrate Platform'),
},
plugins: [
externalAlias('@utils/shadow-css', '../client/shadow-css.js'),
externalAlias('@app-data', '@stencil/core/internal/app-data'),
externalAlias('@app-globals', '@stencil/core/internal/app-globals'),
],
};
const internalHydrateRunnerBundle: ESBuildOptions = {
...getBaseEsbuildOptions(),
entryPoints: [join(hydrateSrcDir, 'runner', 'index.js')],
external,
format: 'esm',
platform: 'node',
outfile: join(outputInternalHydrateDir, 'runner.js'),
banner: {
js: getBanner(opts, 'Stencil Hydrate Runner'),
},
plugins: [
externalAlias('@utils/shadow-css', '../client/shadow-css.js'),
externalAlias('@app-data', '@stencil/core/internal/app-data'),
externalAlias('@hydrate-factory', '@stencil/core/hydrate-factory'),
],
};
return [internalHydratePlatformBundle, internalHydrateRunnerBundle];
}
async function createHydrateRunnerDtsBundle(opts: BuildOptions, inputHydrateDir: string, outputDir: string) {
// bundle @stencil/core/internal/hydrate/runner.d.ts
const dtsEntry = join(inputHydrateDir, 'runner', 'index.d.ts');
const dtsContent = await bundleDts(opts, dtsEntry);
const outputPath = join(outputDir, 'runner.d.ts');
await fs.writeFile(outputPath, dtsContent);
}
================================================
FILE: scripts/esbuild/internal-platform-testing.ts
================================================
import type { BuildOptions as ESBuildOptions } from 'esbuild';
import fs from 'fs-extra';
import { join } from 'path';
import { BuildOptions } from '../utils/options';
import { writePkgJson } from '../utils/write-pkg-json';
import { externalAlias, externalNodeModules, getBaseEsbuildOptions, getEsbuildAliases } from './utils';
/**
* Get an ESBuild configuration object for the internal testing bundle. This
* function also has side-effects which set things up for the bundle to be built
* correctly, like writing a `package.json` file to disk.
*
* @param opts build options
* @returns a promise wrapping an object holding options for ESBuild
*/
export async function getInternalTestingBundle(opts: BuildOptions): Promise {
const inputTestingPlatform = join(opts.srcDir, 'testing', 'platform', 'index.ts');
const outputTestingPlatformDir = join(opts.output.internalDir, 'testing');
await fs.emptyDir(outputTestingPlatformDir);
// write @stencil/core/internal/testing/package.json
writePkgJson(opts, outputTestingPlatformDir, {
name: '@stencil/core/internal/testing',
description:
'Stencil internal testing platform to be imported by the Stencil Compiler. Breaking changes can and will happen at any time.',
main: 'index.js',
});
// Copy JSX runtime files for automatic JSX transform support
const srcJsxDir = join(opts.srcDir, 'internal', 'testing');
const jsxFiles = ['jsx-runtime.js', 'jsx-runtime.d.ts', 'jsx-dev-runtime.js', 'jsx-dev-runtime.d.ts'];
await Promise.all(jsxFiles.map((file) => fs.copyFile(join(srcJsxDir, file), join(outputTestingPlatformDir, file))));
const internalTestingAliases = {
...getEsbuildAliases(),
'@platform': inputTestingPlatform,
'@stencil/core/mock-doc': '../../mock-doc/index.cjs',
};
const external: string[] = [...externalNodeModules, '../../mock-doc/index.cjs'];
const internalTestingBuildOptions: ESBuildOptions = {
...getBaseEsbuildOptions(),
entryPoints: [inputTestingPlatform],
bundle: true,
format: 'cjs',
outfile: join(outputTestingPlatformDir, 'index.js'),
platform: 'node',
logLevel: 'info',
external,
alias: internalTestingAliases,
plugins: [
externalAlias('@app-data', '@stencil/core/internal/app-data'),
externalAlias('@utils/shadow-css', '../client/shadow-css.js'),
],
};
return internalTestingBuildOptions;
}
================================================
FILE: scripts/esbuild/internal.ts
================================================
import { generateDtsBundle } from 'dts-bundle-generator';
import type { BuildOptions as ESBuildOptions } from 'esbuild';
import fs from 'fs-extra';
import { join } from 'path';
import { bundleDts, cleanDts } from '../utils/bundle-dts';
import type { BuildOptions } from '../utils/options';
import { writePkgJson } from '../utils/write-pkg-json';
import { getInternalAppDataBundles } from './internal-app-data';
import { getInternalAppGlobalsBundles } from './internal-app-globals';
import { getInternalClientBundles } from './internal-platform-client';
import { getInternalPlatformHydrateBundles } from './internal-platform-hydrate';
import { getInternalTestingBundle } from './internal-platform-testing';
import { getBaseEsbuildOptions, runBuilds } from './utils';
/**
* Run the build for the `internal/` directory, copying and modifying files
* as-needed while also creating and then building the various bundles that need
* to be written to `internal/`.
*
* @param opts Build options for the current build
* @returns a Promise wrapping the state of the build
*/
export async function buildInternal(opts: BuildOptions) {
const inputInternalDir = join(opts.buildDir, 'internal');
await fs.emptyDir(opts.output.internalDir);
await copyStencilInternalDts(opts, opts.output.internalDir);
await copyUtilsDtsFiles(opts);
await copyStencilCoreEntry(opts);
// copy @stencil/core/internal default entry, which defaults to client
// but we're not exposing all of Stencil's internal code (only the types)
await fs.copyFile(join(inputInternalDir, 'default.js'), join(opts.output.internalDir, 'index.js'));
// write @stencil/core/internal/package.json
writePkgJson(opts, opts.output.internalDir, {
name: '@stencil/core/internal',
description:
'Stencil internals only to be imported by the Stencil Compiler. Breaking changes can and will happen at any time.',
main: 'index.js',
types: 'index.d.ts',
sideEffects: false,
});
// this is used in several of our bundles, so we bundle it here in one spot
const shadowCSSBundle: ESBuildOptions = {
...getBaseEsbuildOptions(),
entryPoints: [join(opts.srcDir, 'utils', 'shadow-css.ts')],
format: 'esm',
outfile: join(opts.output.internalDir, 'client', 'shadow-css.js'),
platform: 'node',
};
const clientPlatformBundles = await getInternalClientBundles(opts);
const hydratePlatformBundles = await getInternalPlatformHydrateBundles(opts);
const appDataBundles = await getInternalAppDataBundles(opts);
const appGlobalsBundles = await getInternalAppGlobalsBundles(opts);
const internalTestingBundle = await getInternalTestingBundle(opts);
return runBuilds(
[
shadowCSSBundle,
...clientPlatformBundles,
...hydratePlatformBundles,
internalTestingBundle,
...appDataBundles,
...appGlobalsBundles,
],
opts,
);
}
async function copyStencilCoreEntry(opts: BuildOptions) {
// write @stencil/core entry
const stencilCoreSrcDir = join(opts.srcDir, 'internal', 'stencil-core');
const stencilCoreDstDir = join(opts.output.internalDir, 'stencil-core');
await fs.ensureDir(stencilCoreDstDir);
await fs.copy(stencilCoreSrcDir, stencilCoreDstDir);
}
/**
* Copy `.d.ts` files built from `src/utils` to `internal/utils` so that types
* exported from utility modules can be referenced by other typedefs (in
* particular by our declarations).
*
* Some modules within `@utils` incorporate external types which aren't bundled
* so we selectively copy only `.d.ts` files which are 1) standalone and 2) export
* a type that other modules in the codebase (in, for instance, `src/compiler/`
* or `src/cli/`) depend on.
*
* @param opts options for the rollup build
*/
const copyUtilsDtsFiles = async (opts: BuildOptions) => {
const outputDirPath = join(opts.output.internalDir, 'utils');
await fs.ensureDir(outputDirPath);
// copy the `.d.ts` file corresponding to `src/utils/result.ts`
const resultDtsFilePath = join(opts.buildDir, 'utils', 'result.d.ts');
const resultDtsOutputFilePath = join(opts.output.internalDir, 'utils', 'result.d.ts');
await fs.copyFile(resultDtsFilePath, resultDtsOutputFilePath);
const utilsIndexDtsPath = join(opts.output.internalDir, 'utils', 'index.d.ts');
// here we write a simple module that re-exports `./result` so that imports
// elsewhere like `import { result } from '@utils'` will resolve correctly
await fs.writeFile(utilsIndexDtsPath, `export * as result from "./result"`);
};
async function copyStencilInternalDts(opts: BuildOptions, outputInternalDir: string) {
const declarationsInputDir = join(opts.buildDir, 'declarations');
// copy to @stencil/core/internal
// @stencil/core/internal/index.d.ts
const indexDtsSrcPath = join(declarationsInputDir, 'index.d.ts');
const indexDtsDestPath = join(outputInternalDir, 'index.d.ts');
let indexDts = cleanDts(await fs.readFile(indexDtsSrcPath, 'utf8'));
indexDts = prependExtModules(indexDts);
await fs.writeFile(indexDtsDestPath, indexDts);
// @stencil/core/internal/stencil-private.d.ts
const privateDtsSrcPath = join(declarationsInputDir, 'stencil-private.d.ts');
const privateDtsDestPath = join(outputInternalDir, 'stencil-private.d.ts');
let privateDts = cleanDts(await fs.readFile(privateDtsSrcPath, 'utf8'));
// @stencil/core/internal/child_process.d.ts
const childProcessSrcPath = join(declarationsInputDir, 'child_process.d.ts');
const childProcessDestPath = join(outputInternalDir, 'child_process.d.ts');
// we generate a tiny tiny bundle here of just
// `src/declarations/child_process.ts` so that `internal/stencil-private.d.ts`
// can import from `'./child_process'` without worrying about resolving the
// types from `node_modules`.
const childProcessDts = generateDtsBundle([
{
filePath: childProcessSrcPath,
libraries: {
// we need to mark this library so that types imported from it are inlined
inlinedLibraries: ['child_process'],
},
output: {
noBanner: true,
exportReferencedTypes: false,
},
},
]).join('\n');
await fs.writeFile(childProcessDestPath, childProcessDts);
// the private `.d.ts` imports the `Result` type from the `@utils` module, so
// we need to rewrite the path so it imports from the right relative path
privateDts = privateDts.replace('@utils', './utils');
await fs.writeFile(privateDtsDestPath, privateDts);
// @stencil/core/internal/stencil-public.compiler.d.ts
const compilerDtsSrcPath = join(declarationsInputDir, 'stencil-public-compiler.d.ts');
const compilerDtsDestPath = join(outputInternalDir, 'stencil-public-compiler.d.ts');
const compilerDts = cleanDts(await fs.readFile(compilerDtsSrcPath, 'utf8'));
await fs.writeFile(compilerDtsDestPath, compilerDts);
// @stencil/core/internal/stencil-public-docs.d.ts
const docsDtsSrcPath = join(declarationsInputDir, 'stencil-public-docs.d.ts');
const docsDtsDestPath = join(outputInternalDir, 'stencil-public-docs.d.ts');
// We bundle with `dts-bundle-generator` here to ensure that when the `docs-json`
// OT writes a `docs.d.ts` file based on this file it is fully portable.
const docsDts = await bundleDts(opts, docsDtsSrcPath, {
// we want to suppress the `dts-bundle-generator` banner here because we do
// our own later on
noBanner: true,
// we also don't want the types which are inlined into our bundled file to
// be re-exported, which will change the 'surface' of the module
exportReferencedTypes: false,
});
await fs.writeFile(docsDtsDestPath, docsDts);
// @stencil/core/internal/stencil-public-runtime.d.ts
const runtimeDtsSrcPath = join(declarationsInputDir, 'stencil-public-runtime.d.ts');
const runtimeDtsDestPath = join(outputInternalDir, 'stencil-public-runtime.d.ts');
const runtimeDts = cleanDts(await fs.readFile(runtimeDtsSrcPath, 'utf8'));
await fs.writeFile(runtimeDtsDestPath, runtimeDts);
// @stencil/core/internal/stencil-ext-modules.d.ts (.svg/.css)
const srcExtModuleOutput = join(opts.srcDir, 'declarations', 'stencil-ext-modules.d.ts');
const dstExtModuleOutput = join(outputInternalDir, 'stencil-ext-modules.d.ts');
await fs.copyFile(srcExtModuleOutput, dstExtModuleOutput);
}
function prependExtModules(content: string) {
return `/// (async (resolveBundle, rejectBundle) => {
const outputFile = path.join(outputDir, entryFileName);
const cachedFile = path.join(cachedDir, entryFileName) + (opts.isProd ? '.min.js' : '');
const cachedExists = fs.existsSync(cachedFile);
if (cachedExists) {
await fs.copyFile(cachedFile, outputFile);
resolveBundle();
return;
}
const whitelist = new Set(['child_process', 'os', 'typescript']);
const webpackConfig: Configuration = {
entry: path.join(opts.srcDir, 'sys', 'node', 'bundles', entryFileName),
output: {
path: outputDir,
filename: entryFileName,
libraryTarget: 'commonjs',
},
target: 'node',
node: {
__dirname: false,
__filename: false,
},
externals(data, callback) {
const { request } = data;
if (request?.match(/^(\.{0,2})\//)) {
// absolute and relative paths are not externals
return callback(null, undefined);
}
if (request === '@stencil/core/mock-doc') {
return callback(null, '../../mock-doc');
}
if (typeof request === 'string' && whitelist.has(request)) {
// we specifically do not want to bundle these imports
resolve.sync(request);
return callback(null, request);
}
// bundle this import
callback(undefined, undefined);
},
resolve: {
alias: {
'@utils': path.join(opts.buildDir, 'utils', 'index.js'),
postcss: path.join(opts.nodeModulesDir, 'postcss'),
'source-map': path.join(opts.nodeModulesDir, 'source-map'),
chalk: path.join(opts.bundleHelpersDir, 'empty.js'),
},
},
optimization: {
minimize: false,
},
mode: 'production',
};
console.log(`[sys-node] bundleExternal ${entryFileName} via webpack`);
webpack(webpackConfig, async (err, stats) => {
try {
console.log(`[sys-node] bundleExternal ${entryFileName} success, err: ${err}, stats: ${stats}`);
const { minify } = await import('terser');
if (err && err.message) {
rejectBundle(err);
} else if (stats) {
const info = stats.toJson({ errors: true });
if (stats.hasErrors() && info && info.errors) {
const webpackError = info.errors.join('\n');
rejectBundle(webpackError);
} else {
let code = await fs.readFile(outputFile, 'utf8');
if (opts.isProd) {
try {
const minifyResults = await minify(code);
if (minifyResults.code) {
code = minifyResults.code;
}
} catch (e) {
rejectBundle(e);
return;
}
}
await fs.writeFile(cachedFile, code);
await fs.writeFile(outputFile, code);
resolveBundle();
}
}
} catch (e) {
rejectBundle(e);
}
});
});
}
================================================
FILE: scripts/esbuild/testing.ts
================================================
import type { BuildOptions as ESBuildOptions, Plugin } from 'esbuild';
import fs from 'fs-extra';
import path from 'path';
import { getBanner } from '../utils/banner';
import type { BuildOptions } from '../utils/options';
import { writePkgJson } from '../utils/write-pkg-json';
import {
externalAlias,
externalNodeModules,
getBaseEsbuildOptions,
getEsbuildAliases,
getFirstOutputFile,
runBuilds,
} from './utils';
const EXTERNAL_TESTING_MODULES = [
'constants',
'rollup',
'@rollup/plugin-commonjs',
'@rollup/plugin-node-resolve',
'yargs',
'zlib',
];
export async function buildTesting(opts: BuildOptions) {
const inputDir = path.join(opts.buildDir, 'testing');
const sourceDir = path.join(opts.srcDir, 'testing');
await fs.emptyDir(opts.output.testingDir);
await Promise.all([
// copy jest testing entry files
fs.copy(path.join(opts.scriptsBundlesDir, 'helpers', 'jest'), opts.output.testingDir),
copyTestingInternalDts(opts, inputDir),
]);
// write package.json
writePkgJson(opts, opts.output.testingDir, {
name: '@stencil/core/testing',
description: 'Stencil testing suite.',
main: 'index.js',
types: 'index.d.ts',
});
const external = [
...EXTERNAL_TESTING_MODULES,
...externalNodeModules,
'../internal/testing/*',
'../cli/index.cjs',
'../sys/node/index.js',
'../compiler/stencil.js',
];
const aliases = getEsbuildAliases();
const testingEsbuildOptions: ESBuildOptions = {
...getBaseEsbuildOptions(),
entryPoints: [path.join(sourceDir, 'index.ts')],
bundle: true,
format: 'cjs',
outfile: path.join(opts.output.testingDir, 'index.js'),
platform: 'node',
logLevel: 'info',
external,
/**
* set `write: false` so that we can run the `onEnd` hook
* in `lazyRequirePlugin` and modify the imports
*/
write: false,
alias: aliases,
banner: { js: getBanner(opts, `Stencil Testing`, true) },
plugins: [
externalAlias('@app-data', '@stencil/core/internal/app-data'),
externalAlias('@platform', '@stencil/core/internal/testing'),
externalAlias('../internal/testing/index.js', '@stencil/core/internal/testing'),
externalAlias('@stencil/core/dev-server', '../dev-server/index.js'),
externalAlias('@stencil/core/mock-doc', '../mock-doc/index.cjs'),
lazyRequirePlugin(opts, [
'@stencil/core/internal/app-data',
'@stencil/core/internal/testing',
'../dev-server/index.js',
'../internal/testing/index.js',
'../mock-doc/index.cjs',
]),
ignorePuppeteerDependency(opts),
],
};
return runBuilds([testingEsbuildOptions], opts);
}
function getLazyRequireFn(opts: BuildOptions) {
return fs.readFileSync(path.join(opts.bundleHelpersDir, 'lazy-require.js'), 'utf8').trim();
}
function lazyRequirePlugin(opts: BuildOptions, moduleIds: string[]): Plugin {
return {
name: 'lazyRequirePlugin',
setup(build) {
build.onEnd(async (buildResult) => {
const bundle = getFirstOutputFile(buildResult);
let code = Buffer.from(bundle.contents).toString();
for (const moduleId of moduleIds) {
const str = `require("${moduleId}")`;
while (code.includes(str)) {
code = code.replace(str, `_lazyRequire("${moduleId}")`);
}
}
code = code.replace(`"use strict";`, `"use strict";\n\n${getLazyRequireFn(opts)}`);
return fs.writeFile(bundle.path, code);
});
},
};
}
/**
* To avoid having user to install puppeteer for building their app (even if
* they don't use e2e testing), we ignore the puppeteer dependency in the
* generated d.ts file.
*
* @param opts build options
* @returns an ESbuild plugin
*/
function ignorePuppeteerDependency(opts: BuildOptions): Plugin {
return {
name: 'ignorePuppeteerDependency',
setup(build) {
build.onEnd(async () => {
await writePatchedPuppeteerDts(opts);
});
},
};
}
export async function copyTestingInternalDts(opts: BuildOptions, inputDir: string) {
// copy testing d.ts files
await fs.copy(path.join(inputDir), path.join(opts.output.testingDir), {
filter: (f) => {
if (f.endsWith('.d.ts')) {
return true;
}
if (fs.statSync(f).isDirectory() && !f.includes('platform')) {
return true;
}
return false;
},
});
}
/**
* Write a patched version of
* `src/testing/puppeteer/puppeteer-declarations.d.ts` which has a `@ts-ignore`
* added to prevent a type-checking error if a Stencil project does not have
* puppeteer installed.
*
* @param opts build options
*/
export async function writePatchedPuppeteerDts(opts: BuildOptions) {
const typeFilePath = path.join(opts.output.testingDir, 'puppeteer', 'puppeteer-declarations.d.ts');
const updatedFileContent = (await fs.readFile(typeFilePath, 'utf8'))
.split('\n')
.reduce((lines, line) => {
if (line.endsWith(`from 'puppeteer';`)) {
lines.push('// @ts-ignore - avoid requiring puppeteer as dependency');
}
lines.push(line);
return lines;
}, [] as string[])
.join('\n');
await fs.writeFile(typeFilePath, updatedFileContent);
}
================================================
FILE: scripts/esbuild/utils/alias-plugin.ts
================================================
import { join } from 'path';
import type { PartialResolvedId, Plugin } from 'rollup';
import type { BuildOptions } from '../../utils/options';
/**
* Creates a rollup plugin for resolving identifiers while simultaneously externalizing them
* @param opts the options being used during a build
* @returns a rollup plugin with a build hook for resolving various identifiers
*/
export function aliasPlugin(opts: BuildOptions): Plugin {
const alias = new Map([
['@app-data', '@stencil/core/internal/app-data'],
['@app-globals', '@stencil/core/internal/app-globals'],
['@hydrate-factory', '@stencil/core/hydrate-factory'],
['@stencil/core/mock-doc', '@stencil/core/mock-doc'],
['@stencil/core/testing', '@stencil/core/testing'],
['@dev-server-process', './server-process.js'],
]);
// ensure we use the same one
const helperResolvers = new Set(['is-resolvable', 'path-is-absolute']);
// ensure we use the same one
const nodeResolvers = new Map([['source-map', join(opts.nodeModulesDir, 'source-map', 'source-map.js')]]);
const empty = new Set([
// we never use chalk, but many projects still pull it in
'chalk',
]);
return {
name: 'aliasPlugin',
/**
* A rollup build hook for resolving identifiers. [Source](https://rollupjs.org/guide/en/#resolveid)
* @param id the importee exactly as it is written in an import statement in the source code
* @returns a resolution to an import to a different id, potentially externalizing it from the bundle simultaneously
*/
resolveId(id: string): PartialResolvedId | string | null | undefined {
const externalId = alias.get(id);
if (externalId) {
return {
id: externalId,
external: true,
};
}
if (id === '@runtime') {
return join(opts.buildDir, 'runtime', 'index.js');
}
if (id === '@utils') {
return join(opts.buildDir, 'utils', 'index.js');
}
if (id === '@utils/shadow-css') {
return join(opts.buildDir, 'utils', 'shadow-css.js');
}
if (id === '@environment') {
return join(opts.buildDir, 'compiler', 'sys', 'environment.js');
}
if (id === '@sys-api-node') {
return join(opts.buildDir, 'sys', 'node', 'index.js');
}
if (id === '@stencil/core/cli') {
return join(opts.buildDir, 'cli', 'index.js');
}
if (helperResolvers.has(id)) {
return join(opts.bundleHelpersDir, `${id}.js`);
}
if (empty.has(id)) {
return join(opts.bundleHelpersDir, 'empty.js');
}
if (nodeResolvers.has(id)) {
return nodeResolvers.get(id);
}
return null;
},
};
}
================================================
FILE: scripts/esbuild/utils/content-types.ts
================================================
import fs from 'fs-extra';
import { join } from 'path';
import type { BuildOptions } from '../../utils/options';
export async function createContentTypeData(opts: BuildOptions) {
// create a focused content-type lookup object from
// the mime db json file
const mimeDbSrcPath = join(opts.nodeModulesDir, 'mime-db', 'db.json');
const mimeDbJson = await fs.readJson(mimeDbSrcPath);
const extData: { ext: string; mimeType: string }[] = [];
Object.keys(mimeDbJson).forEach((mimeType) => {
const mimeTypeData = mimeDbJson[mimeType];
if (Array.isArray(mimeTypeData.extensions)) {
mimeTypeData.extensions.forEach((ext: string) => {
extData.push({
ext,
mimeType,
});
});
}
});
const exts: Record = {};
extData
.sort((a, b) => {
if (a.ext < b.ext) return -1;
if (a.ext > b.ext) return 1;
return 0;
})
.forEach((x: any) => (exts[x.ext] = x.mimeType));
return `export default ${JSON.stringify(exts)}`;
}
================================================
FILE: scripts/esbuild/utils/index.ts
================================================
import type { BuildOptions as ESBuildOptions, BuildResult as ESBuildResult, OutputFile, Plugin } from 'esbuild';
import { build, context } from 'esbuild';
import { BuildOptions } from '../../utils/options';
/**
* Aliases which map the module identifiers we set in `paths` in `tsconfig.json` to
* bundles (built either with esbuild or with rollup).
*
* @returns a map of aliases to bundle entry points, relative to the root directory
*/
export function getEsbuildAliases(): Record {
return {
// node module redirection
chalk: 'ansi-colors',
// mapping aliases to top-level bundle entrypoints
'@stencil/core/testing': '../testing/index.js',
'@stencil/core/compiler': '../compiler/stencil.js',
'@stencil/core/dev-server': '../dev-server/index.js',
'@stencil/core/mock-doc': '../mock-doc/index.cjs',
'@stencil/core/internal/testing': '../internal/testing/index.js',
'@stencil/core/cli': '../cli/index.cjs',
'@sys-api-node': '../sys/node/index.js',
};
}
/**
* Node modules which should be universally marked as external
*
* Note that we should not rely on this to mark node.js built-in modules as
* external. Doing so will override esbuild's automatic marking of those modules
* as side-effect-free, which allows imports from them to be properly
* tree-shaken.
*/
export const externalNodeModules = [
'@jest/core',
'@jest/reporters',
'@microsoft/typescript-etw',
'expect',
'fsevents',
'jest',
'jest-cli',
'jest-config',
'jest-message-id',
'jest-pnp-resolver',
'jest-environment-node',
'jest-runner',
'puppeteer',
'puppeteer-core',
'yargs',
];
/**
* A helper which runs an array of esbuild, uh, _builds_
*
* This accepts an array of build configurations and will either run a
* synchronous build _or_ run them all in watch mode, depending on the
* {@link BuildOptions['isWatch']} setting.
*
* @param builds the array of outputs to build
* @param opts Stencil build options
* @returns a Promise representing the execution of the builds
*/
export function runBuilds(builds: ESBuildOptions[], opts: BuildOptions): Promise<(void | ESBuildResult)[]> {
if (opts.isWatch) {
return Promise.all(
builds.map(async (buildConfig) => {
const ctx = await context(buildConfig);
return ctx.watch();
}),
);
} else {
return Promise.all(builds.map(build));
}
}
/**
* Get base esbuild options which we want to always have set for all of our
* bundles
*
* @returns a base set of options
*/
export function getBaseEsbuildOptions(): ESBuildOptions {
const options: ESBuildOptions = {
bundle: true,
legalComments: 'inline',
logLevel: 'info',
target: getEsbuildTargets(),
};
// if the `build` sub-command is called with the `DEBUG` env var, like
//
// DEBUG=true npm run build
//
// then we should produce sourcemaps.
if (process.env.DEBUG) {
options.sourcemap = 'linked';
}
return options;
}
/**
* Get build targets with minimal supported browser versions
* @see https://stenciljs.com/docs/support-policy#browser-support
* @returns an array of build targets
*/
export function getEsbuildTargets(): string[] {
return ['node16', 'chrome79', 'edge79', 'firefox70', 'safari14'];
}
/**
* Alias and mark a module as external at the same time
*
* @param moduleId the module ID to alias and externalize
* @param resolveToPath the path to which imports of the module should be rewritten
* @returns an Esbuild plugin
*/
export function externalAlias(moduleId: string, resolveToPath: string): Plugin {
return {
name: 'externalAliases',
setup(build) {
build.onResolve({ filter: new RegExp(`^${moduleId}$`) }, () => {
return {
path: resolveToPath,
external: true,
};
});
},
};
}
/**
* Extract the first {@link OutputFile} record from an Esbuild
* {@link BuildResult}. This _may_ not be present, so in order to guarantee
* type safety this function throws if such an `OutputFile` cannot be found.
*
* @throws if no `OutputFile` can be found.
* @param buildResult the Esbuild build result in which to look
* @returns the OutputFile
*/
export function getFirstOutputFile(buildResult: ESBuildResult): OutputFile {
const bundle = buildResult.outputFiles?.[0];
if (!bundle) {
throw new Error('Could not find an output file in the BuildResult!');
}
return bundle;
}
================================================
FILE: scripts/esbuild/utils/parse5.ts
================================================
import rollupCommonjs from '@rollup/plugin-commonjs';
import rollupResolve from '@rollup/plugin-node-resolve';
import fs from 'fs-extra';
import { join } from 'path';
import { rollup } from 'rollup';
import type { BuildOptions } from '../../utils/options';
import { aliasPlugin } from './alias-plugin';
/**
* Bundles parse5 to be used in the Stencil output. Writes the results to disk and returns its contents. The file
* written to disk may be used as a simple cache to speed up subsequent build times.
* @param opts the options being used during a build of the Stencil compiler
* @returns a tuple holding 1) contents of the file containing parse5 and 2) the file path where it's written
*/
export async function bundleParse5(opts: BuildOptions): Promise<[contents: string, path: string]> {
const fileName = `parse5-${opts.parse5Version.replace(/\./g, '_')}-bundle-cache${opts.isProd ? '.min' : ''}.js`;
const cacheFile = join(opts.scriptsBuildDir, fileName);
try {
return [await fs.readFile(cacheFile, 'utf8'), cacheFile];
} catch (e) {}
const rollupBuild = await rollup({
input: '@parse5-entry',
plugins: [
{
name: 'parse5EntryPlugin',
/**
* A rollup build hook for resolving @parse5-entry [Source](https://rollupjs.org/guide/en/#resolveid)
* @param id the importee exactly as it is written in an import statement in the source code
* @returns a string that resolves an import to some id
*/
resolveId(id: string): string | null {
if (id === '@parse5-entry') {
return id;
}
return null;
},
/**
* A rollup build hook for intercepting how parse5's entry package is processed
* [Source](https://rollupjs.org/guide/en/#load)
* @param id the path of the module to load
* @returns source code to act as a proxy for @parse5-entry
*/
load(id: string): string | null {
if (id === '@parse5-entry') {
return `export { parse, parseFragment } from 'parse5';`;
}
return null;
},
},
aliasPlugin(opts),
rollupResolve(),
rollupCommonjs(),
],
});
const { output } = await rollupBuild.generate({
format: 'iife',
name: 'PARSE5',
footer: ['export const parse = PARSE5.parse;', 'export const parseFragment = PARSE5.parseFragment;'].join('\n'),
strict: false,
});
let code = output[0].code;
const { minify } = await import('terser');
if (opts.isProd) {
const minified = await minify(code, {
ecma: 2018,
module: true,
compress: {
ecma: 2018,
passes: 2,
},
format: {
ecma: 2018,
comments: false,
},
});
if (minified.code) {
code = minified.code;
}
}
code = `// Parse5 ${opts.parse5Version}\n` + code;
await fs.writeFile(cacheFile, code);
return [code, cacheFile];
}
================================================
FILE: scripts/esbuild/utils/terser.ts
================================================
import fs from 'fs-extra';
import { join } from 'path';
import { rollup } from 'rollup';
import type { BuildOptions } from '../../utils/options';
/**
* Creates a bundle containing Terser
* @param opts the options being used during a build
* @returns a tuple containing the bundled Terser code and the path where it
* was written
*/
export async function bundleTerser(opts: BuildOptions): Promise<[content: string, path: string]> {
if (!opts.terserVersion) {
throw new Error('Terser version not set on build opts!');
}
const fileName = `terser-${opts.terserVersion.replace(/\./g, '_')}-bundle-cache${opts.isProd ? '.min' : ''}.js`;
const cacheFile = join(opts.scriptsBuildDir, fileName);
try {
const content = await fs.readFile(cacheFile, 'utf8');
return [content, cacheFile];
} catch (e) {}
const rollupBuild = await rollup({
input: join(opts.nodeModulesDir, 'terser', 'main.js'),
external: ['source-map'],
});
const { output } = await rollupBuild.generate({
format: 'es',
strict: false,
});
let code = output[0].code;
const { minify } = await import('terser');
if (opts.isProd) {
const minified = await minify(code, {
ecma: 2018,
compress: {
ecma: 2018,
passes: 2,
},
format: {
ecma: 2018,
comments: false,
},
});
if (minified.code) {
code = minified.code;
}
}
code = `// Terser ${opts.terserVersion}\n` + code;
await fs.writeFile(cacheFile, code);
return [code, cacheFile];
}
================================================
FILE: scripts/esbuild/utils/typescript-source.ts
================================================
import fs from 'fs-extra';
import { join } from 'path';
import type { BuildOptions } from '../../utils/options';
/**
* Bundles the TypeScript compiler in the Stencil output. This function also performs several optimizations and
* modifications to the TypeScript source.
* @param tsPath a path to the TypeScript compiler
* @param opts the options being used during a build of the Stencil compiler
* @returns the modified TypeScript source
*/
export async function bundleTypeScriptSource(tsPath: string, opts: BuildOptions): Promise {
const cacheFile = tsCacheFilePath(opts);
try {
// check if we've already cached this bundle
return await fs.readFile(cacheFile, 'utf8');
} catch (e) {}
// get the source typescript.js file to modify
let code = await fs.readFile(tsPath, 'utf8');
// As of 5.0, because typescript is now bundled with esbuild the structure of
// the file we're dealing with here (`lib/typescript.js`) has changed.
// Previously there was an iife which got an object as an argument and just
// stuck properties onto it, something like
//
// ```js
// var ts = (function (ts) {
// ts.someMethod = () => { ... };
// })(ts || ts = {});
// ```
//
// as of 5.0 it instead looks (conceptually) something like:
//
// ```js
// var ts = (function () {
// const ts = {}
// const define = (name, value) => {
// Object.defineProperty(ts, name, value, { enumerable: true })
// }
// define('someMethod', () => { ... })
// return ts;
// })();
// ```
//
// Note that the call to `Object.defineProperty` does not set `configurable` to `true`
// (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty#description)
// which means that later calls to do something like
//
// ```ts
// import ts from 'typescript';
//
// ts.someMethod = function myReplacementForSomeMethod () {
// ...
// };
// ```
//
// will fail because without `configurable: true` you can't re-assign
// properties.
//
// All well and good, except for the fact that our patching of typescript to
// use for instance the in-memory file system depends on us being able to
// monkey-patch typescript in exactly this way. So in order to retain our
// current approach to patching TypeScript we need to edit this file in order
// to add `configurable: true` to the options passed to
// `Object.defineProperty`:
const TS_PROP_DEFINER = `__defProp(target, name, { get: all[name], enumerable: true });`;
const TS_PROP_DEFINER_RECONFIGURABLE = `__defProp(target, name, { get: all[name], enumerable: true, configurable: true });`;
code = code.replace(TS_PROP_DEFINER, TS_PROP_DEFINER_RECONFIGURABLE);
const jestTypesciptFilename = join(opts.scriptsBuildDir, 'typescript-modified-for-jest.js');
await fs.writeFile(jestTypesciptFilename, code);
// TODO(STENCIL-839): investigate minification issue w/ typescript 5.0
// const { minify } = await import('terser');
// if (opts.isProd) {
// const minified = await minify(code, {
// ecma: 2018,
// // module: true,
// compress: {
// ecma: 2018,
// passes: 2,
// },
// format: {
// ecma: 2018,
// comments: false,
// },
// });
// code = minified.code;
// }
await fs.writeFile(cacheFile, code);
return code;
}
/**
* Get the file path to which the cached, modified version of TypeScript will
* be written
*
* @param opts build options for the current Stencil build
* @returns the path where the modified TypeScript source can be found
*/
export function tsCacheFilePath(opts: BuildOptions): string {
const fileName = `typescript-${opts.typescriptVersion.replace(/\./g, '_')}-bundle-cache${
opts.isProd ? '.min' : ''
}.js`;
const cacheFile = join(opts.scriptsBuildDir, fileName);
return cacheFile;
}
================================================
FILE: scripts/index.ts
================================================
import { join } from 'path';
import * as build from './build';
// This path is relative to the final location of the compiled script, not its TypeScript source
const stencilProjectRoot = join(__dirname, '..');
const args = process.argv.slice(2);
build.run(stencilProjectRoot, args);
================================================
FILE: scripts/release-tasks.ts
================================================
import color from 'ansi-colors';
import Listr, { ListrTask } from 'listr';
import { buildAll } from './build';
import { BuildOptions } from './utils/options';
import { isPrereleaseVersion, isValidVersionInput, SEMVER_INCREMENTS, updateChangeLog } from './utils/release-utils';
/**
* We have to wrap `execa` in a promise to ensure it works with `Listr`. `Listr` uses rxjs under the hood which
* seems to have issues with `execa`'s `ResultPromise` as it never resolves a task.
* @param command command to run
* @param args arguments to pass to the command
* @param options `execa` options
* @returns a promise that resolves with the stdout and stderr of the command
*/
async function execa(command: string, args: string[], options?: any) {
/**
* consecutive imports are cached and don't have an impact on the execution speed
*/
const { execa: execaOrig } = await import('execa');
return new Promise<{ stdout: string; stderr: string }>((resolve, reject) => {
const run = execaOrig(command, args, options);
run.then(
({ stdout, stderr }) =>
resolve({
stdout: stdout as unknown as string,
stderr: stderr as unknown as string,
}),
(err) => reject(err),
);
});
}
/**
* Runs a litany of tasks used to ensure a safe release of a new version of Stencil
* @param opts build options containing the metadata needed to release a new version of Stencil
* @param args stringified arguments used to influence the release steps that are taken
*/
export async function runReleaseTasks(opts: BuildOptions, args: ReadonlyArray): Promise {
const rootDir = opts.rootDir;
const pkg = opts.packageJson;
const tasks: ListrTask[] = [];
const newVersion = opts.version;
const isDryRun = args.includes('--dry-run') || opts.version.includes('dryrun');
let tagPrefix: string;
if (isDryRun) {
console.log(color.bold.yellow(`\n 🏃 Dry Run!\n`));
}
if (!opts.isPublishRelease) {
/**
* For automated and manual releases, always verify that the version provided to the release scripts is a valid
* semver 'word' (e.g. 'major', 'minor', etc.) or version (e.g. 1.0.0)
*/
tasks.push({
title: 'Validate version',
task: () => {
if (!isValidVersionInput(opts.version)) {
throw new Error(`Version should be either ${SEMVER_INCREMENTS.join(', ')}, or a valid semver version.`);
}
},
skip: () => isDryRun,
});
}
if (opts.isPublishRelease) {
tasks.push({
title: 'Check for pre-release version',
task: () => {
if (!pkg.private && isPrereleaseVersion(newVersion) && !opts.tag) {
throw new Error(
'You must specify a dist-tag using --tag when publishing a pre-release version. This prevents accidentally tagging unstable versions as "latest". https://docs.npmjs.com/cli/dist-tag',
);
}
},
});
}
tasks.push({
/**
* When we both pre-release and release, it's beneficial to ensure that the tag does not already exist in git.
* Doing so ought to catch out of the ordinary circumstances that ought to be investigated.
*/
title: 'Check git tag existence',
task: () =>
execa('git', ['fetch'])
// Retrieve the prefix for a version string - https://docs.npmjs.com/cli/v7/using-npm/config#tag-version-prefix
.then(() => execa('npm', ['config', 'get', 'tag-version-prefix']))
.then(
({ stdout }) => (tagPrefix = stdout),
() => {},
)
// verify that a tag for the new version string does not already exist by checking the output of
// `git rev-parse --verify`
.then(() => execa('git', ['rev-parse', '--quiet', '--verify', `refs/tags/${tagPrefix}${newVersion}`]))
.then(
({ stdout }) => {
if (stdout) {
throw new Error(`Git tag \`${tagPrefix}${newVersion}\` already exists.`);
}
},
(err) => {
// Command fails with code 1 and no output if the tag does not exist, even though `--quiet` is provided
// https://github.com/sindresorhus/np/pull/73#discussion_r72385685
if (err.stdout !== '' || err.stderr !== '') {
throw err;
}
},
),
skip: () => isDryRun,
});
tasks.push(
{
title: `Install npm dependencies ${color.dim('(npm ci)')}`,
task: () => execa('npm', ['ci'], { cwd: rootDir }),
// for pre-releases, this step will occur in GitHub after the PR has been created.
// for actual releases, we'll need to build + bundle stencil in order to publish it to npm.
skip: () => !opts.isPublishRelease,
},
{
title: `Transpile Stencil ${color.dim('(tsc.prod)')}`,
task: () => execa('npm', ['run', 'tsc.prod'], { cwd: rootDir }),
// for pre-releases, this step will occur in GitHub after the PR has been created.
// for actual releases, we'll need to build + bundle stencil in order to publish it to npm.
skip: () => !opts.isPublishRelease,
},
{
title: `Bundle @stencil/core ${color.dim('(' + opts.buildId + ')')}`,
task: () => buildAll(opts),
// for pre-releases, this step will occur in GitHub after the PR has been created.
// for actual releases, we'll need to build + bundle stencil in order to publish it to npm.
skip: () => !opts.isPublishRelease,
},
);
if (!opts.isPublishRelease) {
tasks.push(
{
title: `Set package.json version to ${color.bold.yellow(opts.version)}`,
task: async () => {
// use `--no-git-tag-version` to ensure that the tag for the release is not prematurely created
await execa('npm', ['version', '--no-git-tag-version', opts.version], { cwd: rootDir });
},
},
{
title: `Generate ${opts.version} Changelog ${opts.vermoji}`,
task: async () => {
await updateChangeLog(opts);
},
},
);
}
if (opts.isPublishRelease) {
tasks.push(
{
title: 'Publish @stencil/core to npm',
task: () => {
const cmd = 'npm';
const cmdArgs = ['publish'].concat(opts.tag ? ['--tag', opts.tag] : []).concat(['--provenance']);
if (isDryRun) {
return console.log(`[dry-run] ${cmd} ${cmdArgs.join(' ')}`);
}
return execa(cmd, cmdArgs, { cwd: rootDir });
},
},
{
title: 'Tagging the latest git commit',
task: () => {
const cmd = 'git';
const cmdArgs = ['tag', `v${opts.version}`];
if (isDryRun) {
return console.log(`[dry-run] ${cmd} ${cmdArgs.join(' ')}`);
}
return execa(cmd, cmdArgs, { cwd: rootDir });
},
},
{
title: 'Pushing git tags',
task: () => {
const cmd = 'git';
const cmdArgs = ['push', '--tags'];
if (isDryRun) {
return console.log(`[dry-run] ${cmd} ${cmdArgs.join(' ')}`);
}
return execa(cmd, cmdArgs, { cwd: rootDir });
},
},
);
}
const listr = new Listr(tasks);
try {
await listr.run();
} catch (err: any) {
console.log(`\n🤒 ${color.red(err)}\n`);
console.log(err);
process.exit(1);
}
if (opts.isPublishRelease) {
console.log(
`\n ${opts.vermoji} ${color.bold.magenta(pkg.name)} ${color.bold.yellow(newVersion)} published!! ${
opts.vermoji
}\n`,
);
} else {
console.log(
`\n ${opts.vermoji} ${color.bold.magenta(pkg.name)} ${color.bold.yellow(
newVersion,
)} prepared, check the diffs and commit ${opts.vermoji}\n`,
);
}
}
================================================
FILE: scripts/release.ts
================================================
import color from 'ansi-colors';
import fs from 'fs-extra';
import { join } from 'path';
import { runReleaseTasks } from './release-tasks';
import { BuildOptions, getOptions } from './utils/options';
import { getNewVersion } from './utils/release-utils';
import { getLatestVermoji } from './utils/vermoji';
/**
* Runner for creating a release of Stencil
* @param rootDir the root directory of the Stencil repository
* @param args stringified arguments used to influence the release steps that are taken
* @returns a void promise
*/
export async function release(rootDir: string, args: ReadonlyArray): Promise {
const buildDir = join(rootDir, 'build');
if (args.includes('--ci-prepare')) {
await fs.emptyDir(buildDir);
const prepareOpts = getOptions(rootDir, {
isCI: true,
isPublishRelease: false,
isProd: true,
});
const versionIdx = args.indexOf('--version');
if (versionIdx === -1 || versionIdx === args.length) {
console.log(`\n${color.bold.red('No `--version [VERSION]` argument was found. Exiting')}\n`);
process.exit(1);
}
if (prepareOpts.packageJson.version) {
prepareOpts.version = getNewVersion(prepareOpts.packageJson.version, args[versionIdx + 1]);
}
await prepareRelease(prepareOpts, args);
console.log(`${color.bold.blue('Release Prepared!')}`);
}
if (args.includes('--ci-publish')) {
const prepareOpts = getOptions(rootDir, {
isCI: true,
isPublishRelease: false,
isProd: true,
});
// this was bumped already, we just need to copy it from package.json into this field
if (prepareOpts.packageJson.version) {
prepareOpts.version = prepareOpts.packageJson.version;
}
// we generated a vermoji during the preparation step, let's grab it from the changelog
prepareOpts.vermoji = getLatestVermoji(prepareOpts.changelogPath);
const tagIdx = args.indexOf('--tag');
let newTag = null;
if (tagIdx === -1 || tagIdx === args.length) {
console.log(`\n${color.bold.yellow('No `--tag [TAG]` argument was found.')}\n`);
} else if (args[tagIdx + 1] === 'use_pkg_json_version') {
console.log(
`\n${color.bold.green(
'The default package.json version will be used for the tag. No additional tags will be applied.',
)}\n`,
);
} else {
newTag = args[tagIdx + 1];
console.log(`\n${color.bold.green(`Set '--tag' argument to '${newTag}'.`)}\n`);
}
console.log(`${color.bold.blue(`Version: ${prepareOpts.version}`)}`);
console.log(`${color.bold.blue(`Tag: ${newTag}`)}`);
const publishOpts = getOptions(rootDir, {
buildId: prepareOpts.buildId,
version: prepareOpts.version,
vermoji: prepareOpts.vermoji,
isCI: prepareOpts.isCI,
isPublishRelease: true,
isProd: true,
tag: newTag ?? undefined,
});
return await publishRelease(publishOpts, args);
}
}
/**
* Prepares a release of Stencil
* @param opts build options containing the metadata needed to release a new version of Stencil
* @param args stringified arguments used to influence the release steps that are taken
*/
async function prepareRelease(opts: BuildOptions, args: ReadonlyArray): Promise {
const pkg = opts.packageJson;
const oldVersion = opts.packageJson.version;
console.log(
`\nPrepare to publish ${opts.vermoji} ${color.bold.magenta(pkg.name)} ${color.dim(`(currently ${oldVersion})`)}\n`,
);
try {
await runReleaseTasks(opts, args);
} catch (err: any) {
console.log('\n', color.red(err), '\n');
process.exit(0);
}
}
/**
* Initiates publishing a Stencil release.
* @param opts build options containing the metadata needed to publish a new version of Stencil
* @param args stringified arguments used to influence the steps that are taken
* @returns a void promise
*/
async function publishRelease(opts: BuildOptions, args: ReadonlyArray): Promise {
const pkg = opts.packageJson;
if (opts.version !== pkg.version) {
throw new Error(
`Prepare release data (${opts.version}) and package.json (${pkg.version}) versions do not match. Try re-running release prepare.`,
);
}
console.log(`\nPublish ${opts.vermoji} ${color.bold.magenta(pkg.name)} ${color.yellow(`${opts.version}`)}\n`);
try {
await runReleaseTasks(opts, args);
} catch (err: any) {
console.log('\n', color.red(err), '\n');
process.exit(0);
}
}
================================================
FILE: scripts/test/copy-readme.js
================================================
/**
* This script copies a supplemental README file to the location where it will be overwritten
* during the `docs-readme` output target test. The purpose of this step is to ensure that
* the file is in a known state before the test runs, avoiding issues with Git detecting
* unexpected changes to the file.
*
* Context:
* - During the `docs-readme` tests, a README file is overwritten as part of the test process.
* - The expected result of the test must be tracked by Git; otherwise, Git will detect a "dirty"
* state and the test will fail.
* - This behaviour can be used to our advantage: if the file is overwritten with the supplemental
* file but not overwritten back to the expected result, Git will detect a dirty state, causing
* the test to fail. This ensures that the correct action is taken by the code being tested.
*
* Usage:
* - This script is executed as part of the `prepare.readmes` npm script.
* - It copies `readme-supplemental.md` to `readme.md` in the appropriate directory.
*/
const fs = require('fs');
const path = require('path');
// Define source and destination paths
const src = path.resolve(
__dirname,
'../../test/docs-readme/custom-readme-output-overwrite/components/styleurls-component/readme-supplemental.md',
);
const dest = path.resolve(
__dirname,
'../../test/docs-readme/custom-readme-output-overwrite/components/styleurls-component/readme.md',
);
// Copy the file
try {
fs.copyFileSync(src, dest);
console.log(`Copied ${src} to ${dest}`);
} catch (err) {
console.error(`Error copying file: ${err.message}`);
process.exit(1);
}
================================================
FILE: scripts/test/validate-build.ts
================================================
import fs from 'fs-extra';
import { dirname, join, relative } from 'path';
import { rollup } from 'rollup';
import ts, { ModuleResolutionKind, ScriptTarget } from 'typescript';
import url from 'url';
import { NODE_BUILTINS } from '../utils/constants';
import { BuildOptions, getOptions } from '../utils/options';
import { PackageData } from '../utils/write-pkg-json';
/**
* Used to triple check that the final build files
* ready to be published are good to go
*/
const pkgs: TestPackage[] = [
{
// cli
packageJson: 'cli/package.json',
},
{
// compiler
packageJson: 'compiler/package.json',
files: ['compiler/lib.d.ts', 'compiler/lib.dom.d.ts'],
},
{
// dev-server
packageJson: 'dev-server/package.json',
files: [
'dev-server/static/favicon.ico',
'dev-server/templates/directory-index.html',
'dev-server/templates/initial-load.html',
'dev-server/connector.html',
'dev-server/server-process.js',
'dev-server/server-worker-thread.js',
'dev-server/visualstudio.vbs',
'dev-server/xdg-open',
],
},
{
// internal/app-data
packageJson: 'internal/app-data/package.json',
},
{
// internal/client
packageJson: 'internal/client/package.json',
files: ['internal/client/polyfills/'],
},
{
// internal/hydrate
packageJson: 'internal/hydrate/package.json',
files: ['internal/hydrate/runner.d.ts', 'internal/hydrate/runner.js'],
},
{
// internal/testing
packageJson: 'internal/testing/package.json',
},
{
// internal
packageJson: 'internal/package.json',
files: [
'internal/stencil-core/index.cjs',
'internal/stencil-core/index.js',
'internal/stencil-core/index.d.ts',
'internal/stencil-ext-modules.d.ts',
'internal/stencil-private.d.ts',
'internal/stencil-public-compiler.d.ts',
'internal/stencil-public-docs.d.ts',
'internal/stencil-public-runtime.d.ts',
],
},
{
// mock-doc
packageJson: 'mock-doc/package.json',
},
{
// screenshot
packageJson: 'screenshot/package.json',
files: [
'screenshot/compare/',
'screenshot/connector.js',
'screenshot/local-connector.js',
'screenshot/pixel-match.js',
],
},
{
// sys/node
packageJson: 'sys/node/package.json',
files: ['sys/node/autoprefixer.js', 'sys/node/graceful-fs.js', 'sys/node/node-fetch.js'],
},
{
// testing
packageJson: 'testing/package.json',
files: [
'testing/jest-environment.js',
'testing/jest-preprocessor.js',
'testing/jest-preset.js',
'testing/jest-runner.js',
'testing/jest-setuptestframework.js',
],
},
{
// @stencil/core
packageJson: 'package.json',
packageJsonFiles: [
'bin/',
'cli/',
'compiler/',
'dev-server/',
'internal/',
'mock-doc/',
'screenshot/',
'sys/',
'testing/',
],
files: ['CHANGELOG.md', 'LICENSE.md', 'readme.md'],
hasBin: true,
},
];
/**
* Validate that certain files were written to disk during the build, and that
* these files tree-shake correctly.
*
* @param rootDir the root of the Stencil repository
*/
export async function validateBuild(rootDir: string): Promise {
const dtsEntries: string[] = [];
const opts = getOptions(rootDir);
pkgs.forEach((testPkg) => {
validatePackage(opts, testPkg, dtsEntries);
});
console.log(`🐡 Validated packages`);
validateDts(opts, dtsEntries);
await validateCompiler(opts);
await validateTreeshaking(opts);
}
/**
* Validates a bundled package/sub-module. Validation steps include verifying that various fields in `package.json` are
* filled out and file references are valid.
* @param opts build options to be used to validate a package
* @param testPkg the package to validate
* @param dtsEntries a reference to .d.ts files to collect while validating the package
*/
function validatePackage(opts: BuildOptions, testPkg: TestPackage, dtsEntries: string[]): void {
const rootDir = opts.rootDir;
if (testPkg.packageJson) {
testPkg.packageJson = join(rootDir, testPkg.packageJson);
const pkgDir = dirname(testPkg.packageJson);
const pkgJson: PackageData = require(testPkg.packageJson);
if (!pkgJson.name) {
throw new Error('missing package.json name: ' + testPkg.packageJson);
}
if (!pkgJson.main) {
throw new Error('missing package.json main: ' + testPkg.packageJson);
}
if (testPkg.packageJsonFiles) {
if (!Array.isArray(pkgJson.files)) {
throw new Error(testPkg.packageJson + ' missing "files" property');
}
pkgJson.files.forEach((f) => {
if (f === '!**/*.map' || f === '!**/*.stub.ts' || f === '!**/*.stub.tsx') {
// skip sourcemaps, stub files
return;
}
const pkgFile = join(pkgDir, f);
fs.accessSync(pkgFile);
});
testPkg.packageJsonFiles.forEach((testPkgFile) => {
if (!pkgJson.files?.includes(testPkgFile)) {
throw new Error(testPkg.packageJson + ' missing file ' + testPkgFile);
}
const filePath = join(pkgDir, testPkgFile);
fs.accessSync(filePath);
});
}
if (testPkg.hasBin && !pkgJson.bin) {
throw new Error(testPkg.packageJson + ' missing bin');
}
if (pkgJson.bin) {
Object.keys(pkgJson.bin).forEach((k) => {
if (pkgJson.bin?.[k]) {
const binExe = join(pkgDir, pkgJson.bin[k]);
fs.accessSync(binExe);
}
});
}
const mainIndex = join(pkgDir, pkgJson.main);
fs.accessSync(mainIndex);
if (pkgJson.module) {
const moduleIndex = join(pkgDir, pkgJson.module);
fs.accessSync(moduleIndex);
}
if (pkgJson.browser) {
const browserIndex = join(pkgDir, pkgJson.browser);
fs.accessSync(browserIndex);
}
if (pkgJson.types) {
const pkgTypes = join(pkgDir, pkgJson.types);
fs.accessSync(pkgTypes);
dtsEntries.push(pkgTypes);
}
}
if (testPkg.files) {
testPkg.files.forEach((file) => {
const filePath = join(rootDir, file);
fs.statSync(filePath);
});
}
}
/**
* Validate the .d.ts files used in the output are semantically and syntactically correct
* @param opts build options to be used to validate .d.ts files
* @param dtsEntries the .d.ts files to validate
*/
function validateDts(opts: BuildOptions, dtsEntries: string[]): void {
const program = ts.createProgram(dtsEntries, {
baseUrl: '.',
paths: {
'@stencil/core/mock-doc': [join(opts.rootDir, 'mock-doc', 'index.d.ts')],
'@stencil/core/internal': [join(opts.rootDir, 'internal', 'index.d.ts')],
'@stencil/core/internal/testing': [join(opts.rootDir, 'internal', 'testing', 'index.d.ts')],
},
moduleResolution: ModuleResolutionKind.NodeJs,
target: ScriptTarget.ES2016,
});
const tsDiagnostics = program.getSemanticDiagnostics().concat(program.getSyntacticDiagnostics());
if (tsDiagnostics.length > 0) {
const host = {
getCurrentDirectory: () => ts.sys.getCurrentDirectory(),
getNewLine: () => ts.sys.newLine,
getCanonicalFileName: (f: string) => f,
};
throw new Error('🧨 ' + ts.formatDiagnostics(tsDiagnostics, host));
}
console.log(`🐟 Validated dts files`);
}
/**
* Validates the Stencil compiler. This includes verifying that the compiler, CLI and sys API can be instantiated,
* smoke testing the compiler's transpilation, and running a small task in the CLI.
* @param opts build options to be used to validate the compiler
*/
async function validateCompiler(opts: BuildOptions): Promise {
const compilerPath = url.pathToFileURL(join(opts.output.compilerDir, 'stencil.js')).pathname;
const cliPath = url.pathToFileURL(join(opts.output.cliDir, 'index.cjs')).pathname;
const sysNodePath = url.pathToFileURL(join(opts.output.sysNodeDir, 'index.js')).pathname;
const compiler = await import(compilerPath);
const cli = await import(cliPath);
const sysNodeApi = await import(sysNodePath);
const nodeLogger = sysNodeApi.createNodeLogger();
const nodeSys = sysNodeApi.createNodeSys({ process });
if (!nodeSys || nodeSys.name !== 'node' || nodeSys.version.length < 4) {
throw new Error(`🧨 unable to validate sys node`);
}
console.log(`🐳 Validated sys node, current ${nodeSys.name} version: ${nodeSys.version}`);
const validated = await compiler.loadConfig({
config: {
logger: nodeLogger,
sys: nodeSys,
},
});
console.log(`${compiler.vermoji} Validated compiler: ${compiler.version}`);
const transpileResults = compiler.transpileSync('const m: string = `transpile!`;', {
target: 'es5',
});
if (
!transpileResults ||
transpileResults.diagnostics.length > 0 ||
!transpileResults.code.startsWith(`var m = "transpile!";`)
) {
console.error(transpileResults);
throw new Error(`🧨 transpileSync error`);
}
console.log(`🐋 Validated compiler.transpileSync()`);
const orgConsoleLog = console.log;
let loggedVersion = '';
console.log = (value: string) => (loggedVersion = value);
// this runTask is intentionally not wrapped in telemetry helpers
await cli.runTask(compiler, validated.config, 'version');
console.log = orgConsoleLog;
if (typeof loggedVersion !== 'string' || loggedVersion.length < 4) {
throw new Error(`🧨 unable to validate compiler. loggedVersion: "${loggedVersion}"`);
}
console.log(`🐬 Validated cli`);
}
/**
* Validate tree shaking for various modules in the output
* @param opts build options to be used to validate tree-shaking
*/
async function validateTreeshaking(opts: BuildOptions) {
await validateModuleTreeshake(opts, 'app-data', join(opts.output.internalDir, 'app-data', 'index.js'));
await validateModuleTreeshake(opts, 'client', join(opts.output.internalDir, 'client', 'index.js'));
await validateModuleTreeshake(opts, 'patch-browser', join(opts.output.internalDir, 'client', 'patch-browser.js'));
await validateModuleTreeshake(opts, 'shadow-css', join(opts.output.internalDir, 'client', 'shadow-css.js'));
await validateModuleTreeshake(opts, 'hydrate', join(opts.output.internalDir, 'hydrate', 'index.js'));
await validateModuleTreeshake(opts, 'stencil-core', join(opts.output.internalDir, 'stencil-core', 'index.js'));
await validateModuleTreeshake(opts, 'cli', join(opts.output.cliDir, 'index.js'));
}
/**
* Validates tree-shaking for a single module & entrypoint
* @param opts build options to be used to validate tree-shaking for a specific module
* @param moduleName the module to validate
* @param entryModulePath the entrypoint to validate
*/
async function validateModuleTreeshake(opts: BuildOptions, moduleName: string, entryModulePath: string): Promise {
// this is a song, 'agadoo' by Black Lace
const virtualInputId = `@g@doo`;
const entryId = `@entry-module`;
const outputFile = join(opts.scriptsBuildDir, `treeshake_${moduleName}.js`);
const bundle = await rollup({
external: NODE_BUILTINS,
input: virtualInputId,
treeshake: {
moduleSideEffects: false,
},
plugins: [
{
name: 'stencilResolver',
resolveId(id) {
if (id === '@stencil/core/internal/client' || id === '@stencil/core') {
return join(opts.output.internalDir, 'client', 'index.js');
}
if (id === '@stencil/core/internal/app-data') {
return join(opts.output.internalDir, 'app-data', 'index.js');
}
if (id === '@stencil/core/internal/app-globals') {
return id;
}
if (id === virtualInputId) {
return id;
}
if (id === entryId) {
return entryModulePath;
}
},
load(id) {
if (id === '@stencil/core/internal/app-globals') {
return 'export const globalScripts = () => {};\nexport const globalStyles = "";';
}
if (id === virtualInputId) {
return `import "${entryId}";`;
}
},
},
],
onwarn(warning) {
if (warning.code !== 'EMPTY_BUNDLE') {
throw warning;
}
},
});
const o = await bundle.generate({
format: 'es',
});
const output = o.output[0];
const outputCode = output.code.trim();
await fs.writeFile(outputFile, outputCode);
if (outputCode !== '') {
console.error(`\nTreeshake output: ${outputFile}\n`);
throw new Error(`🧨 Not all code was not treeshaken (treeshooken? treeshaked?)`);
}
console.log(`🌳 validated treeshake: ${relative(opts.rootDir, entryModulePath)}`);
}
/**
* Represents a package/submodule of the bundled Stencil output to validate
*/
interface TestPackage {
packageJson?: string;
packageJsonFiles?: string[];
files?: string[];
hasBin?: boolean;
}
================================================
FILE: scripts/test/validate-testing.js
================================================
const testing = require('../../testing/index.js');
const input = `
import { Component, Prop } from '@stencil/core';
@Component({
tag: 'my-cmp'
})
export class MyCmp {
@Prop() prop: boolean;
}
`;
const output = testing.transpile(input);
if (output.diagnostics.length > 0) {
const msg = output.diagnostics.map((d) => d.messageText).join('\n');
throw new Error('Testing transpile error: \n' + msg);
}
console.log(`🐠 Validated testing suite`);
================================================
FILE: scripts/tsconfig.json
================================================
{
"compilerOptions": {
"alwaysStrict": true,
"strict": true,
"allowSyntheticDefaultImports": true,
"esModuleInterop": true,
"forceConsistentCasingInFileNames": true,
"lib": [
"dom",
"es2021"
],
"module": "NodeNext",
"moduleResolution": "nodenext",
"skipLibCheck": true,
"outDir": "build/",
"pretty": true,
"target": "ES2020",
"incremental": false,
"useUnknownInCatchVariables": true
},
"include": [
"**/*.ts",
"types/*.d.ts"
],
"exclude": [
"**/*.spec.ts"
]
}
================================================
FILE: scripts/types/rollup-plugin-node-resolve.d.ts
================================================
declare module '@rollup/plugin-node-resolve';
================================================
FILE: scripts/updateSelectorEngine.ts
================================================
import cp from 'node:child_process';
import fs from 'node:fs/promises';
import path from 'node:path';
/**
* This script updates the JQuery selector engine for the mock-doc package
* to the latest version.
*
* To run it, use the following command:
* ```sh
* npm run tsc.scripts
* npm run build.updateSelectorEngine
* ```
*/
const rootDir = path.resolve(__dirname, '..');
const jqueryDepDir = path.resolve(rootDir, 'node_modules', 'jquery');
const WINDOW_MOCK = `{
document: {
createElement() {
return {};
},
nodeType: 9,
documentElement: {
nodeType: 1,
nodeName: 'HTML'
}
}
}`;
async function run() {
console.log('updating JQuery Selector engine...');
await runCommand(`npm install --ignore-scripts`, jqueryDepDir);
await runCommand(`npm run build -- --include=selector`, jqueryDepDir);
const jqueryPkgJSON = JSON.parse(await fs.readFile(path.resolve(jqueryDepDir, 'package.json'), 'utf8'));
const thirdPartyDir = path.resolve(__dirname, '../../src/mock-doc/third-party');
await fs.mkdir(thirdPartyDir, { recursive: true });
const originalContent = await fs.readFile(path.resolve(jqueryDepDir, 'dist', 'jquery.js'), 'utf8');
/**
* This is a hack to make the jQuery selector engine work with the mock-doc package.
* Using the original jQuery bundle would cause a "RegExpCompiler Allocation failed - process out of memory"
* error due to the way the jQuery object is constructed. The following tweaks to the jQuery bundle
* resolve the issue:
*/
const fixedJQuery = originalContent
/**
* Never run the short-circuiting code due to usage of too many RegExp objects
*/
.replace('if ( !seed ) {', 'if ( false ) {')
/**
* Make jQuery an object to have it garbage collected
*/
.replace('var version = "', `const jQuery = {} as { find: Function };\nvar version = "`)
/**
* Inject window mock directly into iife
*/
.replace(`typeof window !== "undefined" ? window : this`, WINDOW_MOCK)
/**
* Rename the original jQuery function to jQueryOrig
*/
.replace('jQuery = function( selector, context ) {', 'jQueryOrig = function( selector, context ) {')
/**
* Replace use of `jQuery.attr` with `elem.getAttribute` to avoid having to include
* the attributes plugin to the bundle
*/
.replace('jQuery.attr( elem, name )', 'elem.getAttribute( name )')
/**
* make it return jQuery directly rather than relying on a module system
*/
.replace('module.exports = factory( global, true );', 'return factory( global, true );')
.replace('if ( typeof module === "object" && typeof module.exports === "object" ) {', 'if (true) {');
const newContent = `/* eslint-disable */
// @ts-nocheck
/**
* ATTENTION: DO NOT MODIFY THIS FILE
*
* This file is generated by "scripts/updateSelectorEngine.ts" and can be overwritten
* at any time. Don't make changes in here as they will get lost!
*/
export default ${fixedJQuery};
`;
fs.writeFile(path.resolve(thirdPartyDir, 'jquery.ts'), newContent, 'utf8');
console.log(`\nJQuery Selector engine updated to version ${jqueryPkgJSON.version}`);
console.log(`at ${thirdPartyDir} 🎉`);
}
function runCommand(cmd: string, cwd: string) {
return new Promise((resolve, reject) => {
console.log(`> ${cmd}`);
const child = cp.spawn(cmd, { cwd, shell: true });
child.on('error', reject);
child.on('exit', (code) => (code === 0 ? resolve(child) : reject()));
});
}
if (require.main === module) {
run();
}
================================================
FILE: scripts/utils/banner.ts
================================================
import { BuildOptions } from './options';
export function getBanner(opts: BuildOptions, fileName: string, license = false) {
return [
`/*${license ? '!' : ''}`,
` ${fileName} v${opts.version} | MIT Licensed | https://stenciljs.com`,
` */`,
].join('\n');
}
================================================
FILE: scripts/utils/bundle-dts.ts
================================================
import { EntryPointConfig, generateDtsBundle, OutputOptions } from 'dts-bundle-generator';
import fs from 'fs-extra';
import { BuildOptions } from './options';
/**
* A thin wrapper for `dts-bundle-generator` which uses our build options to
* set a few things up
*
* **Note**: this file caches its output to disk, and will return any
* previously cached file if not in a prod environment!
*
* @param opts an object holding information about the current build of Stencil
* @param inputFile the path to the file which should be bundled
* @param outputOptions options for bundling the file
* @param useCache whether or not the bundled file should be cached to disk
* @returns a string containing the bundled typedef
*/
export async function bundleDts(
opts: BuildOptions,
inputFile: string,
outputOptions?: OutputOptions,
useCache = true,
): Promise {
const cachedDtsOutput = inputFile + '-bundled.d.ts';
if (!opts.isProd && useCache) {
try {
return await fs.readFile(cachedDtsOutput, 'utf8');
} catch (e) {}
}
const config: EntryPointConfig = {
filePath: inputFile,
};
if (outputOptions) {
config.output = outputOptions;
}
const outputCode = cleanDts(generateDtsBundle([config]).join('\n'));
if (useCache) {
await fs.writeFile(cachedDtsOutput, outputCode);
}
return outputCode;
}
export function cleanDts(dtsContent: string) {
dtsContent = dtsContent.replace(/\/\/\/ = {}): BuildOptions {
const srcDir = join(rootDir, 'src');
const packageJsonPath = join(rootDir, 'package.json');
const packageLockJsonPath = join(rootDir, 'package-lock.json');
const changelogPath = join(rootDir, 'CHANGELOG.md');
const nodeModulesDir = join(rootDir, 'node_modules');
const typescriptDir = join(nodeModulesDir, 'typescript');
const typescriptLibDir = join(typescriptDir, 'lib');
const buildDir = join(rootDir, 'build');
const scriptsDir = join(rootDir, 'scripts');
const scriptsBuildDir = join(scriptsDir, 'build');
const scriptsBundlesDir = join(scriptsDir, 'esbuild');
const bundleHelpersDir = join(scriptsBundlesDir, 'helpers');
const packageJson: PackageData = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
const buildId = inputOpts.buildId ?? getBuildId();
const version = inputOpts.version ?? getDevVersionId({ buildId, semverVersion: packageJson?.version });
const vermoji =
inputOpts.isProd && !inputOpts.vermoji
? getVermoji(inputOpts.changelogPath ?? changelogPath)
: inputOpts.vermoji ?? '💎';
const typescriptPkg = require(join(typescriptDir, 'package.json'));
const typescriptVersion = typescriptPkg.version;
const terserPkg = getPkg(nodeModulesDir, 'terser');
const terserVersion = terserPkg.version;
const rollupPkg = getPkg(nodeModulesDir, 'rollup');
const rollupVersion = rollupPkg.version;
const parse5Pkg = getPkg(nodeModulesDir, 'parse5');
const parse5Version = parse5Pkg.version;
const jqueryPkg = getPkg(nodeModulesDir, 'jquery');
const jqueryVersion = jqueryPkg.version;
const opts: BuildOptions = {
ghRepoOrg: 'ionic-team',
ghRepoName: 'stencil',
rootDir,
srcDir,
packageJsonPath,
packageLockJsonPath,
changelogPath,
nodeModulesDir,
typescriptDir,
typescriptLibDir,
packageJson,
buildDir,
scriptsDir,
scriptsBuildDir,
scriptsBundlesDir,
bundleHelpersDir,
output: {
cliDir: join(rootDir, 'cli'),
compilerDir: join(rootDir, 'compiler'),
devServerDir: join(rootDir, 'dev-server'),
internalDir: join(rootDir, 'internal'),
mockDocDir: join(rootDir, 'mock-doc'),
screenshotDir: join(rootDir, 'screenshot'),
sysNodeDir: join(rootDir, 'sys', 'node'),
testingDir: join(rootDir, 'testing'),
},
version,
buildId,
isProd: false,
isCI: false,
isWatch: false,
isPublishRelease: false,
vermoji,
tag: 'dev',
jqueryVersion,
parse5Version,
rollupVersion,
terserVersion,
typescriptVersion,
};
Object.assign(opts, inputOpts);
if (opts.isPublishRelease) {
if (!opts.isProd) {
throw new Error('release must also be a prod build');
}
}
return opts;
}
/**
* Generates an object containing versioning information of various packages
* installed at build time
*
* **NOTE** this will mutate the `opts` parameter, adding information about
* the versions used for various dependencies
*
* @param opts the options being used during a build
* @returns an object that contains package names/versions installed at the time a build was invoked
*/
export function createReplaceData(opts: BuildOptions): Record {
const CACHE_BUSTER = 7;
const typescriptPkg = require(join(opts.typescriptDir, 'package.json'));
const transpileId = typescriptPkg.name + typescriptPkg.version + '_' + CACHE_BUSTER;
const terserPkg = getPkg(opts.nodeModulesDir, 'terser');
const minifyJsId = terserPkg.name + terserPkg.version + '_' + CACHE_BUSTER;
const rollupPkg = getPkg(opts.nodeModulesDir, 'rollup');
const bundlerId = rollupPkg.name + rollupPkg.version + '_' + CACHE_BUSTER;
const autoprefixerPkg = getPkg(opts.nodeModulesDir, 'autoprefixer');
const postcssPkg = getPkg(opts.nodeModulesDir, 'postcss');
const optimizeCssId =
autoprefixerPkg.name + autoprefixerPkg.version + '_' + postcssPkg.name + postcssPkg.version + '_' + CACHE_BUSTER;
return {
__BUILDID__: opts.buildId,
'__BUILDID:BUNDLER__': bundlerId,
'__BUILDID:MINIFYJS__': minifyJsId,
'__BUILDID:OPTIMIZECSS__': optimizeCssId,
'__BUILDID:TRANSPILE__': transpileId,
'__VERSION:STENCIL__': opts.version,
'__VERSION:PARSE5__': opts.parse5Version,
'__VERSION:ROLLUP__': opts.rollupVersion,
'__VERSION:JQUERY__': opts.jqueryVersion,
'__VERSION:TERSER__': opts.terserVersion,
'__VERSION:TYPESCRIPT__': opts.typescriptVersion,
__VERMOJI__: opts.vermoji,
};
}
type VersionedPackageData = PackageData & { version: string };
/**
* Retrieves a package from the `node_modules` directory in the given `opts` parameter
* @param nodeModulesDir the node modules directory to search
* @param pkgName the name of the NPM package to retrieve
* @returns information about the retrieved package
*/
function getPkg(nodeModulesDir: string, pkgName: string): VersionedPackageData {
const packageJson = require(join(nodeModulesDir, pkgName, 'package.json'));
if (!packageJson.version) {
throw Error(`Didn't find a version in the packageJson for ${pkgName}!`);
}
return packageJson;
}
export interface BuildOptions {
buildDir: string;
bundleHelpersDir: string;
ghRepoName: string;
ghRepoOrg: string;
nodeModulesDir: string;
rootDir: string;
scriptsBuildDir: string;
scriptsBundlesDir: string;
scriptsDir: string;
srcDir: string;
typescriptDir: string;
typescriptLibDir: string;
output: {
cliDir: string;
compilerDir: string;
devServerDir: string;
internalDir: string;
mockDocDir: string;
screenshotDir: string;
sysNodeDir: string;
testingDir: string;
};
buildId: string;
changelogPath: string;
isCI: boolean;
isProd: boolean;
isPublishRelease: boolean;
isWatch: boolean;
jqueryVersion: string;
packageJson: PackageData;
packageJsonPath: string;
packageLockJsonPath: string;
parse5Version: string;
rollupVersion: string;
tag: string;
terserVersion: string;
typescriptVersion: string;
vermoji: string;
version: string;
}
/**
* Generate a build identifier, which is the Epoch Time in seconds
* @returns the generated build ID
*/
function getBuildId(): string {
return Date.now().toString(10).slice(0, -3);
}
/**
* Describes the contents of a version string for Stencil used in 'non-production' builds (e.g. a one-off dev build)
*/
interface DevVersionContents {
/**
* The build identifier string, used to uniquely identify when the build was generated
*/
buildId: string;
/**
* A semver-compliant string to add to the one-off build version sting, used to identify a base version of Stencil
* that was used in the build.
*/
semverVersion: string | undefined;
}
/**
* Helper function to return the first seven characters of a git SHA
*
* We use the first seven characters for two reasons:
* 1. Seven characters _should_ be enough to uniquely ID a commit in Stencil
* 2. It matches the number of characters used in our CHANGELOG.md
*
* @returns the seven character SHA
*/
function getSevenCharGitSha(): string {
return execSync('git rev-parse HEAD').toString().trim().slice(0, 7);
}
/**
* Helper function to generate a dev build version string of the format:
*
* [BASE_VERSION]-dev.[BUILD_IDENTIFIER].[GIT_SHA]
*
* where:
* - BASE_VERSION is the version of Stencil currently assigned in `package.json`
* - BUILD_IDENTIFIER is a unique identifier for this particular build
* - GIT_SHA is the SHA of the HEAD of the branch this build was created from
*
* @param devVersionContents an object containing the necessary arguments to build a dev-version identifier
* @returns the generated version string
*/
function getDevVersionId(devVersionContents: DevVersionContents): string {
const { buildId, semverVersion } = devVersionContents;
// if `package.json#package` is empty, default to a value that doesn't imply any particular version of Stencil
const version = semverVersion ?? '0.0.0';
// '-' and '-dev.' are a magic substrings that may get checked on startup of a Stencil process.
return version + '-dev.' + buildId + '.' + getSevenCharGitSha();
}
================================================
FILE: scripts/utils/postcss-bundle
================================================
#!/bin/bash
cd ../build
#rm -rf ./postcss
#git clone https://github.com/postcss/postcss.git --depth 1
cd ../..
echo $PWD
./node_modules/.bin/rollup -c ./scripts/utils/postcss-rollup.js
================================================
FILE: scripts/utils/postcss-rollup.js
================================================
import fs from 'fs-extra';
import path from 'path';
const input = require.resolve('postcss');
const output = path.join(__dirname, '..', 'bundles', 'helpers', 'postcss.js');
const postcssPkg = fs.readJSONSync(path.join(input, '..', '..', 'package.json'));
export default {
input,
output: {
format: 'esm',
file: output,
banner: `// postcss esm build from ${postcssPkg.version}`,
},
plugins: [
{
resolveId(importee, importer) {
if (importee.startsWith('.')) {
if (importer && importer.endsWith('.es6')) {
const dir = path.dirname(importer);
return path.join(dir, importee + '.es6');
}
}
},
},
],
};
================================================
FILE: scripts/utils/release-utils.ts
================================================
import color from 'ansi-colors';
import fs from 'fs-extra';
import { join } from 'path';
import semver from 'semver';
import { BuildOptions } from './options';
export const SEMVER_INCREMENTS: ReadonlyArray = [
'patch',
'minor',
'major',
'prepatch',
'preminor',
'premajor',
'prerelease',
];
export const PRERELEASE_VERSIONS: ReadonlyArray = ['prepatch', 'preminor', 'premajor', 'prerelease'];
/**
* Helper function to help determine if a version is valid semver
* @param input the version string to validate
* @returns true if the `input` is valid semver, false otherwise
*/
export const isValidVersion = (input: string) => Boolean(semver.valid(input));
/**
* Determines whether or not a version string is valid. A version string is considered to be 'valid' if it meets one of
* two criteria:
* - it is a valid semver name (e.g. 'patch', 'major', etc.)
* - it is a valid semver string (e.g. '1.0.2')
* @param input the version string to validate
* @returns true if the string is valid, false otherwise
*/
export const isValidVersionInput = (input: string): boolean =>
SEMVER_INCREMENTS.indexOf(input) !== -1 || isValidVersion(input);
/**
* Determines if the provided `version` is a semver pre-release or not
* @param version the version string to evaluate
* @returns true if the `version` is a pre-release, false otherwise
*/
export const isPrereleaseVersion = (version: string): boolean =>
PRERELEASE_VERSIONS.indexOf(version) !== -1 || Boolean(semver.prerelease(version));
/**
* Determine the 'next' version string for a release. The next version can take one of two formats:
* 1. An alphabetic string that is a valid semver name (e.g. 'patch', 'major', etc.)
* 2. A valid semver string (e.g. '1.0.2')
* The value returned by this function is predicated on the format of `oldVersion`. If `oldVersion` is an alphabetic
* semver name, a semver name will be returned (e.g. 'major'). If a valid semver string is provided (e.g. 1.0.2), the
* incremented semver string will be returned (e.g. 2.0.0)
* @param oldVersion the old/current version of the library
* @param input the desired increment unit
* @returns new version's string
*/
export function getNewVersion(oldVersion: string, input: any): string {
const isValidSemverName = SEMVER_INCREMENTS.indexOf(input) === -1;
const incrementedSemverString = semver.inc(oldVersion, input);
if (isValidSemverName) return input;
if (incrementedSemverString !== null) return incrementedSemverString;
throw new Error(`Version should be either ${SEMVER_INCREMENTS.join(', ')} or a valid semver version.`);
}
/**
* Pretty printer for a new version of the library. Generates a new version string based on `inc`
* @param oldVersion the old/current version of Stencil
* @param inc the unit of increment for the new version
* @returns a pretty printed string containing the new version number
*/
export function prettyVersionDiff(oldVersion: string, inc: any): string {
const newVersion = getNewVersion(oldVersion, inc).split('.');
const splitOldVersion = oldVersion.split('.');
let firstVersionChange = false;
const output = [];
for (let i = 0; i < newVersion.length; i++) {
if (newVersion[i] !== splitOldVersion[i] && !firstVersionChange) {
output.push(`${color.dim.cyan(newVersion[i])}`);
firstVersionChange = true;
} else if (newVersion[i].indexOf('-') >= 1) {
let preVersion = [];
preVersion = newVersion[i].split('-');
output.push(`${color.dim.cyan(`${preVersion[0]}-${preVersion[1]}`)}`);
} else {
output.push(color.reset.dim(newVersion[i]));
}
}
return output.join(color.reset.dim('.'));
}
/**
* Write changes to the local CHANGELOG.md on disk.
*
* Stencil uses the Angular-variant of conventional commits; commits must be formatted accordingly in order to be added
* to the changelog properly.
* @param opts build options to be used to update the changelog
*/
export async function updateChangeLog(opts: BuildOptions): Promise {
const ccPath = join(opts.nodeModulesDir, '.bin', 'conventional-changelog');
const ccConfigPath = join(__dirname, 'conventional-changelog-config.js');
const { execa } = await import('execa');
// API Docs for conventional-changelog: https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-core#api
await execa(
'node',
[
ccPath,
'--preset',
'angular',
'--infile',
opts.changelogPath,
'--outfile',
'--same-file',
'--config',
ccConfigPath,
],
{
cwd: opts.rootDir,
},
);
let changelog = await fs.readFile(opts.changelogPath, 'utf8');
changelog = changelog.replace(/\# \[/, '# ' + opts.vermoji + ' [');
await fs.writeFile(opts.changelogPath, changelog);
}
/**
* Generate a GitHub release and create it. This function assumes that the CHANGELOG.md file has been written to disk.
* @param opts build options to be used to create a GitHub release
*/
export async function postGithubRelease(opts: BuildOptions): Promise {
const versionTag = `v${opts.version}`;
const title = `${opts.vermoji} ${opts.version}`;
const lines = (await fs.readFile(opts.changelogPath, 'utf8')).trim().split('\n');
let body = '';
for (let i = 1; i < 500; i++) {
const currentLine = lines[i];
if (currentLine == undefined) {
// we don't test this as `!currentLine`, as an empty string is permitted in the changelog
break;
}
const isMajorOrMinorVersionHeader = currentLine.startsWith('# ');
const isPatchVersionHeader = currentLine.startsWith('## ');
if (isMajorOrMinorVersionHeader || isPatchVersionHeader) {
break;
}
body += currentLine + '\n';
}
// https://docs.github.com/en/github/administering-a-repository/automation-for-release-forms-with-query-parameters
const url = new URL(`https://github.com/${opts.ghRepoOrg}/${opts.ghRepoName}/releases/new`);
url.searchParams.set('tag', versionTag);
const timestamp = new Date().toISOString().substring(0, 10);
// this will be automatically encoded for us, no need to call `encodeURIComponent` here. doing so will result in a
// double encoding, which does not render properly in GitHub
url.searchParams.set('title', `${title} (${timestamp})`);
url.searchParams.set('body', body.trim());
if (opts.tag === 'next' || opts.tag === 'test') {
url.searchParams.set('prerelease', '1');
}
const open = (await import('open')).default;
await open(url.href);
}
================================================
FILE: scripts/utils/test/options.spec.ts
================================================
import path from 'path';
import { BuildOptions, getOptions } from '../options';
import * as Vermoji from '../vermoji';
describe('release options', () => {
describe('getOptions', () => {
const ROOT_DIR = path.join(__dirname, '../../..');
// Friday, February 24, 2023 2:42:09.123 PM, GMT
const FAKE_SYSTEM_TIME_MS = 1677249729123;
const FAKE_SYSTEM_TIME_S = FAKE_SYSTEM_TIME_MS.toString(10).slice(0, -3);
beforeEach(() => {
jest.useFakeTimers();
jest.setSystemTime(FAKE_SYSTEM_TIME_MS);
});
afterEach(() => {
jest.useRealTimers();
});
it('returns the correct default value', () => {
const buildOpts = getOptions(ROOT_DIR);
expect(buildOpts).toEqual({
buildDir: path.join(ROOT_DIR, 'build'),
// More focused tests for `buildId` can be found in another testing suite in this file
buildId: expect.any(String),
bundleHelpersDir: path.join(ROOT_DIR, 'scripts', 'esbuild', 'helpers'),
changelogPath: path.join(ROOT_DIR, 'CHANGELOG.md'),
ghRepoName: 'stencil',
ghRepoOrg: 'ionic-team',
isCI: false,
isProd: false,
isPublishRelease: false,
isWatch: false,
nodeModulesDir: path.join(ROOT_DIR, 'node_modules'),
output: {
cliDir: path.join(ROOT_DIR, 'cli'),
compilerDir: path.join(ROOT_DIR, 'compiler'),
devServerDir: path.join(ROOT_DIR, 'dev-server'),
internalDir: path.join(ROOT_DIR, 'internal'),
mockDocDir: path.join(ROOT_DIR, 'mock-doc'),
screenshotDir: path.join(ROOT_DIR, 'screenshot'),
sysNodeDir: path.join(ROOT_DIR, 'sys', 'node'),
testingDir: path.join(ROOT_DIR, 'testing'),
},
// reads in package.json, skip it verifying it
packageJson: expect.any(Object),
packageJsonPath: path.join(ROOT_DIR, 'package.json'),
packageLockJsonPath: path.join(ROOT_DIR, 'package-lock.json'),
rootDir: ROOT_DIR,
scriptsBuildDir: path.join(ROOT_DIR, 'scripts', 'build'),
scriptsBundlesDir: path.join(ROOT_DIR, 'scripts', 'esbuild'),
scriptsDir: path.join(ROOT_DIR, 'scripts'),
srcDir: path.join(ROOT_DIR, 'src'),
tag: 'dev',
typescriptDir: path.join(ROOT_DIR, 'node_modules', 'typescript'),
typescriptLibDir: path.join(ROOT_DIR, 'node_modules', 'typescript', 'lib'),
vermoji: '💎',
// More focused tests for `version` can be found in another testing suite in this file
version: expect.any(String),
jqueryVersion: expect.any(String),
parse5Version: expect.any(String),
terserVersion: expect.any(String),
rollupVersion: expect.any(String),
typescriptVersion: expect.any(String),
});
});
describe('buildId', () => {
it('defaults the buildId if none is provided', () => {
const { buildId } = getOptions(ROOT_DIR);
expect(buildId).toBeDefined();
expect(buildId).toBe(FAKE_SYSTEM_TIME_S);
});
it('uses the provided the buildId', () => {
const expectedBuildId = 'test-build-id';
const { buildId } = getOptions(ROOT_DIR, { buildId: expectedBuildId });
expect(buildId).toBeDefined();
expect(buildId).toBe(expectedBuildId);
});
});
describe('version', () => {
it('defaults the version if none is provided', () => {
const { version } = getOptions(ROOT_DIR);
expect(version).toBeDefined();
// Expect a version string with the format 0.0.0-dev-[EPOCH_TIME]-[GIT_SHA_7_CHARS]
// or, contain a possible pre-release string like 0.0.0-beta.0-dev-[EPOCH_TIME]-[GIT_SHA_7_CHARS]
expect(version).toMatch(new RegExp(`\\d+\\.\\d+\\.\\d+(-(.{1,}))?-dev.${FAKE_SYSTEM_TIME_S}.\\w{7}`));
});
it('uses the provided version', () => {
const expectedVersion = '3.0.0-dev-1234';
const { version } = getOptions(ROOT_DIR, { version: expectedVersion });
expect(version).toBeDefined();
expect(version).toBe(expectedVersion);
});
});
describe('publish + prod check', () => {
it("throws an error if 'isPublishRelease' is set, but Stencil is not built for 'isProd'", () => {
expect(() => getOptions(ROOT_DIR, { isProd: false, isPublishRelease: true })).toThrow(
'release must also be a prod build',
);
});
it.each>([
{ isProd: false },
{ isPublishRelease: false },
{ isProd: false, isPublishRelease: false },
{ isProd: true, isPublishRelease: false },
{ isProd: true, isPublishRelease: true },
])("does not throw an error for other combinations of 'isPublishRelease' and 'isProd'", (buildOpts) => {
expect(() => getOptions(ROOT_DIR, buildOpts)).not.toThrow();
});
});
describe('vermoji', () => {
let getVermojiSpy: jest.SpyInstance, Parameters>;
beforeEach(() => {
getVermojiSpy = jest.spyOn(Vermoji, 'getVermoji');
getVermojiSpy.mockImplementation((_changelogPath) => '🧀');
});
afterEach(() => {
getVermojiSpy.mockRestore();
});
it('defaults to 💎 for non-prod builds', () => {
expect(getOptions(ROOT_DIR).vermoji).toBe('💎');
});
it.each>([
{ isProd: true, vermoji: '🦄' },
{ isProd: false, vermoji: '🦄' },
])("uses the provided vermoji, regardless of 'isProd'", () => {
const expectedVermoji = '🦄';
const { vermoji } = getOptions(ROOT_DIR, { vermoji: expectedVermoji });
expect(vermoji).toEqual('🦄');
});
it('picks a new vermoji when none is provided for prod builds', () => {
const { vermoji } = getOptions(ROOT_DIR, { isProd: true });
expect(vermoji).toEqual('🧀');
});
});
});
});
================================================
FILE: scripts/utils/test/release-utils.spec.ts
================================================
import fs from 'fs-extra';
import { BuildOptions } from '../options';
// `open` must be mocked before importing the module under test
const openMock = jest.fn();
jest.mock('open', () => openMock);
import { postGithubRelease } from '../release-utils';
describe('release-utils', () => {
describe('postGithubRelease', () => {
jest.useFakeTimers().setSystemTime(new Date('2022-01-01').getTime());
let buildOptions: BuildOptions;
let mockReadFile: jest.SpyInstance, Parameters>;
beforeEach(() => {
mockReadFile = jest.spyOn(fs, 'readFile');
buildOptions = {
changelogPath: 'some/mock/CHANGELOG.md',
ghRepoName: 'stencil',
ghRepoOrg: 'ionic-team',
tag: 'dev',
vermoji: '🚗',
version: '0.0.0',
};
});
afterEach(() => {
jest.clearAllMocks();
});
afterAll(() => {
jest.resetAllMocks();
});
it('creates an empty body if the changelog is empty', async () => {
// Jest isn't smart enough to pick the correct overloaded method, so we must do type assertions to get our spy to
// return a string (as if we called the original with an encoding argument)
mockReadFile.mockResolvedValue('' as unknown as Buffer);
await postGithubRelease(buildOptions);
expect(openMock).toHaveBeenCalledTimes(1);
expect(openMock).toHaveBeenCalledWith(
'https://github.com/ionic-team/stencil/releases/new?tag=v0.0.0&title=%F0%9F%9A%97+0.0.0+%282022-01-01%29&body=',
);
});
it('splits a minor release from a previous patch release', async () => {
const minorReleaseFollowingPatch = `# 🍣 [2.13.0](https://github.com/ionic-team/stencil/compare/v2.12.1...v2.13.0) (2022-01-24)
### Features
* **mock-doc:** add simple MockEvent#composedPath() impl ([#3204](https://github.com/ionic-team/stencil/issues/3204)) ([7b47d96](https://github.com/ionic-team/stencil/commit/7b47d96e1e3c6c821d5c416fbe987646b4cd1551))
* **test:** jest 27 support ([#3189](https://github.com/ionic-team/stencil/issues/3189)) ([10efeb6](https://github.com/ionic-team/stencil/commit/10efeb6f74888f05a13a47d8afc00b5e83a3f3db))
## 🍔 [2.12.1](https://github.com/ionic-team/stencil/compare/v2.12.0...v2.12.1) (2022-01-04)
### Bug Fixes
* **vdom:** properly warn for step attr on input ([#3196](https://github.com/ionic-team/stencil/issues/3196)) ([7ffc02e](https://github.com/ionic-team/stencil/commit/7ffc02e5d07b05de45cbaf4f0cce3f3e165b3eb0))
### Features
* **typings:** add optional key and ref to slot elements ([#3177](https://github.com/ionic-team/stencil/issues/3177)) ([ce27a18](https://github.com/ionic-team/stencil/commit/ce27a18ba8ecdb2cc5401470747a7e9d91e40a44))
`;
// Jest isn't smart enough to pick the correct overloaded method, so we must do type assertions to get our spy to
// return a string (as if we called the original with an encoding argument)
mockReadFile.mockResolvedValue(minorReleaseFollowingPatch as unknown as Buffer);
await postGithubRelease(buildOptions);
expect(openMock).toHaveBeenCalledTimes(1);
expect(openMock).toHaveBeenCalledWith(
'https://github.com/ionic-team/stencil/releases/new?tag=v0.0.0&title=%F0%9F%9A%97+0.0.0+%282022-01-01%29&body=%23%23%23+Features%0A%0A*+**mock-doc%3A**+add+simple+MockEvent%23composedPath%28%29+impl+%28%5B%233204%5D%28https%3A%2F%2Fgithub.com%2Fionic-team%2Fstencil%2Fissues%2F3204%29%29+%28%5B7b47d96%5D%28https%3A%2F%2Fgithub.com%2Fionic-team%2Fstencil%2Fcommit%2F7b47d96e1e3c6c821d5c416fbe987646b4cd1551%29%29%0A*+**test%3A**+jest+27+support+%28%5B%233189%5D%28https%3A%2F%2Fgithub.com%2Fionic-team%2Fstencil%2Fissues%2F3189%29%29+%28%5B10efeb6%5D%28https%3A%2F%2Fgithub.com%2Fionic-team%2Fstencil%2Fcommit%2F10efeb6f74888f05a13a47d8afc00b5e83a3f3db%29%29',
);
});
it('splits a minor release from a previous minor release', async () => {
const minorReleaseFollowingMinor = `# ⛸ [2.12.0](https://github.com/ionic-team/stencil/compare/v2.11.0...v2.12.0) (2021-12-13)
### Bug Fixes
* **cli:** wait for help task to finish before exiting ([#3160](https://github.com/ionic-team/stencil/issues/3160)) ([f10cee1](https://github.com/ionic-team/stencil/commit/f10cee12a8d00e7581fcf13216f01ded46227f49))
* **mock-doc:** make Node.contains() return true for self ([#3150](https://github.com/ionic-team/stencil/issues/3150)) ([f164407](https://github.com/ionic-team/stencil/commit/f164407f7463faba7a3c39afca942c2a26210b82))
* **mock-doc:** allow urls as css values ([#2857](https://github.com/ionic-team/stencil/issues/2857)) ([6faa5f2](https://github.com/ionic-team/stencil/commit/6faa5f2f196ff786ffc4b818ac09708ba5de9b35))
* **sourcemaps:** do not encode inline sourcemaps ([#3163](https://github.com/ionic-team/stencil/issues/3163)) ([b2eb083](https://github.com/ionic-team/stencil/commit/b2eb083306802645ee6e31987917dea942882e46)), closes [#3147](https://github.com/ionic-team/stencil/issues/3147)
### Features
* **dist-custom-elements-bundle:** add deprecation warning ([#3167](https://github.com/ionic-team/stencil/issues/3167)) ([c7b07c6](https://github.com/ionic-team/stencil/commit/c7b07c65265c7d4715f29835632cc6538ea63585))
# 🐌 [2.11.0](https://github.com/ionic-team/stencil/compare/v2.11.0-0...v2.11.0) (2021-11-22)
### Bug Fixes
* **dist-custom-elements:** add ssr checks ([#3131](https://github.com/ionic-team/stencil/issues/3131)) ([9a232ea](https://github.com/ionic-team/stencil/commit/9a232ea368324f49993bd079cfdbc344abd0c69e))
### Features
* **css:** account for escaped ':' in css selectors ([#3087](https://github.com/ionic-team/stencil/issues/3087)) ([6000681](https://github.com/ionic-team/stencil/commit/600068168c86dba9ea610b5e8a0dbba00ff4d1f4))
`;
// Jest isn't smart enough to pick the correct overloaded method, so we must do type assertions to get our spy to
// return a string (as if we called the original with an encoding argument)
mockReadFile.mockResolvedValue(minorReleaseFollowingMinor as unknown as Buffer);
await postGithubRelease(buildOptions);
expect(openMock).toHaveBeenCalledTimes(1);
expect(openMock).toHaveBeenCalledWith(
'https://github.com/ionic-team/stencil/releases/new?tag=v0.0.0&title=%F0%9F%9A%97+0.0.0+%282022-01-01%29&body=%23%23%23+Bug+Fixes%0A%0A*+**cli%3A**+wait+for+help+task+to+finish+before+exiting+%28%5B%233160%5D%28https%3A%2F%2Fgithub.com%2Fionic-team%2Fstencil%2Fissues%2F3160%29%29+%28%5Bf10cee1%5D%28https%3A%2F%2Fgithub.com%2Fionic-team%2Fstencil%2Fcommit%2Ff10cee12a8d00e7581fcf13216f01ded46227f49%29%29%0A*+**mock-doc%3A**+make+Node.contains%28%29+return+true+for+self+%28%5B%233150%5D%28https%3A%2F%2Fgithub.com%2Fionic-team%2Fstencil%2Fissues%2F3150%29%29+%28%5Bf164407%5D%28https%3A%2F%2Fgithub.com%2Fionic-team%2Fstencil%2Fcommit%2Ff164407f7463faba7a3c39afca942c2a26210b82%29%29%0A*+**mock-doc%3A**+allow+urls+as+css+values+%28%5B%232857%5D%28https%3A%2F%2Fgithub.com%2Fionic-team%2Fstencil%2Fissues%2F2857%29%29+%28%5B6faa5f2%5D%28https%3A%2F%2Fgithub.com%2Fionic-team%2Fstencil%2Fcommit%2F6faa5f2f196ff786ffc4b818ac09708ba5de9b35%29%29%0A*+**sourcemaps%3A**+do+not+encode+inline+sourcemaps+%28%5B%233163%5D%28https%3A%2F%2Fgithub.com%2Fionic-team%2Fstencil%2Fissues%2F3163%29%29+%28%5Bb2eb083%5D%28https%3A%2F%2Fgithub.com%2Fionic-team%2Fstencil%2Fcommit%2Fb2eb083306802645ee6e31987917dea942882e46%29%29%2C+closes+%5B%233147%5D%28https%3A%2F%2Fgithub.com%2Fionic-team%2Fstencil%2Fissues%2F3147%29%0A%0A%0A%23%23%23+Features%0A%0A*+**dist-custom-elements-bundle%3A**+add+deprecation+warning+%28%5B%233167%5D%28https%3A%2F%2Fgithub.com%2Fionic-team%2Fstencil%2Fissues%2F3167%29%29+%28%5Bc7b07c6%5D%28https%3A%2F%2Fgithub.com%2Fionic-team%2Fstencil%2Fcommit%2Fc7b07c65265c7d4715f29835632cc6538ea63585%29%29',
);
});
it('splits a patch release from a previous patch release', async () => {
const patchReleaseFollowingPatch = `## ♨️ [2.12.2](https://github.com/ionic-team/stencil/compare/v2.12.1...v2.12.2) (2022-01-24)
### Features
* **mock-doc:** add simple MockEvent#composedPath() impl ([#3204](https://github.com/ionic-team/stencil/issues/3204)) ([7b47d96](https://github.com/ionic-team/stencil/commit/7b47d96e1e3c6c821d5c416fbe987646b4cd1551))
* **test:** jest 27 support ([#3189](https://github.com/ionic-team/stencil/issues/3189)) ([10efeb6](https://github.com/ionic-team/stencil/commit/10efeb6f74888f05a13a47d8afc00b5e83a3f3db))
## 🍔 [2.12.1](https://github.com/ionic-team/stencil/compare/v2.12.0...v2.12.1) (2022-01-04)
### Bug Fixes
* **vdom:** properly warn for step attr on input ([#3196](https://github.com/ionic-team/stencil/issues/3196)) ([7ffc02e](https://github.com/ionic-team/stencil/commit/7ffc02e5d07b05de45cbaf4f0cce3f3e165b3eb0))
### Features
* **typings:** add optional key and ref to slot elements ([#3177](https://github.com/ionic-team/stencil/issues/3177)) ([ce27a18](https://github.com/ionic-team/stencil/commit/ce27a18ba8ecdb2cc5401470747a7e9d91e40a44))
`;
// Jest isn't smart enough to pick the correct overloaded method, so we must do type assertions to get our spy to
// return a string (as if we called the original with an encoding argument)
mockReadFile.mockResolvedValue(patchReleaseFollowingPatch as unknown as Buffer);
await postGithubRelease(buildOptions);
expect(openMock).toHaveBeenCalledTimes(1);
expect(openMock).toHaveBeenCalledWith(
'https://github.com/ionic-team/stencil/releases/new?tag=v0.0.0&title=%F0%9F%9A%97+0.0.0+%282022-01-01%29&body=%23%23%23+Features%0A%0A*+**mock-doc%3A**+add+simple+MockEvent%23composedPath%28%29+impl+%28%5B%233204%5D%28https%3A%2F%2Fgithub.com%2Fionic-team%2Fstencil%2Fissues%2F3204%29%29+%28%5B7b47d96%5D%28https%3A%2F%2Fgithub.com%2Fionic-team%2Fstencil%2Fcommit%2F7b47d96e1e3c6c821d5c416fbe987646b4cd1551%29%29%0A*+**test%3A**+jest+27+support+%28%5B%233189%5D%28https%3A%2F%2Fgithub.com%2Fionic-team%2Fstencil%2Fissues%2F3189%29%29+%28%5B10efeb6%5D%28https%3A%2F%2Fgithub.com%2Fionic-team%2Fstencil%2Fcommit%2F10efeb6f74888f05a13a47d8afc00b5e83a3f3db%29%29',
);
});
});
});
================================================
FILE: scripts/utils/vermoji.ts
================================================
import fs from 'fs-extra';
const UNKNOWN_VERMOJI = '❓';
let vermojis = [
'💯',
'☀️',
'☕️',
'♨️',
'✈️',
'✨',
'❄️',
'❤️',
'☎️',
'⚡️',
'⚽️',
'⚾️',
'⛄️',
'⛑',
'⛰',
'⛱',
'⛲️',
'⛳️',
'⛴',
'⛵️',
'⛷',
'⛸',
'⛹',
'⛺️',
'⭐️',
'🌀',
'🌁',
'🌃',
'🌄',
'🌅',
'🌇',
'🌈',
'🌍',
'🌎',
'🌏',
'🌐',
'🌙',
'🌜',
'🌝',
'🌞',
'🌟',
'🌪',
'🌭',
'🌮',
'🌯',
'🌱',
'🌲',
'🌳',
'🌴',
'🌵',
'🌶',
'🌷',
'🌸',
'🌹',
'🌺',
'🌻',
'🌼',
'🍀',
'🍁',
'🍅',
'🍇',
'🍈',
'🍉',
'🍊',
'🍋',
'🍌',
'🍍',
'🍎',
'🍏',
'🍐',
'🍒',
'🍓',
'🍔',
'🍕',
'🍖',
'🍗',
'🍜',
'🍝',
'🍞',
'🍟',
'🍡',
'🍣',
'🍤',
'🍦',
'🍧',
'🍨',
'🍩',
'🍪',
'🍫',
'🍬',
'🍭',
'🍮',
'🍯',
'🍰',
'🍲',
'🍵',
'🍷',
'🍸',
'🍹',
'🍺',
'🍻',
'🥃',
'🍾',
'🍿',
'🎀',
'🎁',
'🎂',
'🎆',
'🎇',
'🎈',
'🎉',
'🎊',
'🎖',
'🎙',
'🎠',
'🎡',
'🎢',
'🎤',
'🎨',
'🎩',
'🎪',
'🎬',
'🎭',
'🎯',
'🎰',
'🎱',
'🎲',
'🎳',
'🎷',
'🎸',
'🎹',
'🎺',
'🎻',
'🎾',
'🎿',
'🏀',
'🏁',
'🏂',
'🏃',
'🏄',
'🏅',
'🏆',
'🏇',
'🏈',
'🏉',
'🏊',
'🏋',
'🏌',
'🏍',
'🏎',
'🏏',
'🏐',
'🏑',
'🏒',
'🏓',
'🏔',
'🏕',
'🏖',
'🏙',
'🏜',
'🏝',
'🏰',
'🏵',
'🏸',
'🏹',
'🐁',
'🐂',
'🐄',
'🐅',
'🐆',
'🐇',
'🐈',
'🐉',
'🐊',
'🐋',
'🐌',
'🐍',
'🐎',
'🐏',
'🐐',
'🐒',
'🐓',
'🐔',
'🐕',
'🐖',
'🐗',
'🐘',
'🐙',
'🐚',
'🐛',
'🐝',
'🐞',
'🐟',
'🐠',
'🐡',
'🐣',
'🐤',
'🐥',
'🐦',
'🐧',
'🐨',
'🐩',
'🐫',
'🐬',
'🐭',
'🐮',
'🐯',
'🐰',
'🐱',
'🐳',
'🐴',
'🐵',
'🐶',
'🐷',
'🐸',
'🐹',
'🐺',
'🐻',
'🐼',
'🐽',
'🐿',
'👑',
'👒',
'👻',
'👽',
'👾',
'💍',
'💙',
'💚',
'💛',
'💡',
'💥',
'💪',
'💫',
'💾',
'💿',
'📌',
'📍',
'📟',
'🛰',
'📢',
'📣',
'📬',
'📷',
'📺',
'📻',
'🔈',
'🔋',
'🔔',
'🔥',
'🔬',
'🔭',
'🔮',
'🕊',
'🕹',
'🖍',
'🗻',
'😀',
'😃',
'😄',
'😈',
'😊',
'😋',
'😎',
'😛',
'😜',
'😸',
'🤓',
'🤖',
'🚀',
'🚁',
'🚂',
'🚃',
'🚅',
'🚋',
'🚌',
'🚍',
'🚎',
'🚐',
'🚑',
'🚒',
'🚓',
'🚔',
'🚕',
'🚖',
'🚗',
'🚘',
'🚙',
'🚚',
'🚛',
'🚜',
'🚞',
'🚟',
'🚠',
'🚡',
'🚢',
'🚣',
'🚤',
'🚦',
'🚨',
'🚩',
'🛠',
'🛥',
'🛩',
'🛳',
'🤘',
'🦀',
'🦁',
'🦂',
'🦃',
'🦄',
'🧀',
];
// filter out the 'unknown version vermoji'
vermojis = vermojis.filter((vermoji) => vermoji !== UNKNOWN_VERMOJI);
export function getVermoji(changelogPath: string) {
const changelog = fs.readFileSync(changelogPath, 'utf8');
while (true) {
const randomIndex = Math.floor(Math.random() * vermojis.length);
const vermoji = vermojis[randomIndex];
if (changelog.includes(vermoji)) {
vermojis.splice(randomIndex, 1);
if (vermojis.length === 0) {
console.warn(`We're out of Vermoji! Create a task to add some more!`);
return UNKNOWN_VERMOJI;
}
} else {
return vermoji;
}
}
}
/**
* Pull the most recently used vermoji for the provided changelog path
* @param changelogPath the path to the changelog to parse
* @returns the vermoji found in the changelog, otherwise use a default value.
*/
export function getLatestVermoji(changelogPath: string) {
let changelogContents = null;
try {
changelogContents = fs.readFileSync(changelogPath, 'utf8');
} catch (err: unknown) {
console.error(`Unable to read the changelog at path '${changelogPath}' - ${err}.`);
console.error(`Defaulting to ${UNKNOWN_VERMOJI}`);
return UNKNOWN_VERMOJI;
}
if (!changelogContents) {
console.error(`The changelog at '${changelogPath}' was empty!`);
console.error(`Defaulting to ${UNKNOWN_VERMOJI}`);
return UNKNOWN_VERMOJI;
}
// grab the first line of the changelog
const firstLine = changelogContents.trimStart().split('\n')[0];
// match the first line of the changelog with a string that has:
// - one or more pound signs (#), followed by a space
// - capture the first non-space character(s)
const match = firstLine.match(/^#+\s(\S+)/);
// if a match was found, return the value in the first capture group. otherwise, use the default vermoji
return match ? match[1] : UNKNOWN_VERMOJI;
}
================================================
FILE: scripts/utils/write-pkg-json.ts
================================================
import fs from 'fs-extra';
import path from 'path';
import { BuildOptions } from './options';
export function writePkgJson(opts: BuildOptions, pkgDir: string, pkgData: PackageData) {
pkgData.version = opts.version;
pkgData.private = true;
if (pkgData.main && !pkgData.main.startsWith('.')) {
pkgData.main = `./${pkgData.main}`;
}
if (pkgData.module && !pkgData.module.startsWith('.')) {
pkgData.module = `./${pkgData.module}`;
}
if (pkgData.types && !pkgData.types.startsWith('.')) {
pkgData.types = `./${pkgData.types}`;
}
if (pkgData.module && pkgData.main) {
pkgData.type = 'module';
pkgData.exports = {
import: pkgData.module,
require: pkgData.main,
};
}
// idk, i just like a nice pretty standardized order of package.json properties
const formatedPkg: any = {};
PROPS_ORDER.forEach((pkgProp) => {
if (pkgProp in pkgData) {
formatedPkg[pkgProp] = pkgData[pkgProp as keyof PackageData];
}
});
fs.writeFileSync(path.join(pkgDir, 'package.json'), JSON.stringify(formatedPkg, null, 2) + '\n');
}
const PROPS_ORDER = [
'name',
'version',
'description',
'bin',
'main',
'module',
'browser',
'types',
'exports',
'type',
'files',
'private',
'sideEffects',
];
export interface PackageData {
name: string;
description: string;
main: string;
module?: string;
browser?: string;
exports?: any;
type?: string;
types?: string;
version?: string;
dependencies?: string[];
private?: boolean;
license?: string | any;
licenses?: string | any;
author?: string | any;
contributors?: string | any;
homepage?: string;
repository?: any;
files?: string[];
bin?: { [key: string]: string };
sideEffects?: false;
}
================================================
FILE: src/app-data/index.ts
================================================
import type { BuildConditionals } from '@stencil/core/internal';
/**
* A collection of default build flags for a Stencil project.
*
* This collection can be found throughout the Stencil codebase, often imported from the `@app-data` module like so:
* ```ts
* import { BUILD } from '@app-data';
* ```
* and is used to determine if a portion of the output of a Stencil _project_'s compilation step can be eliminated.
*
* e.g. When `BUILD.allRenderFn` evaluates to `false`, the compiler will eliminate conditional statements like:
* ```ts
* if (BUILD.allRenderFn) {
* // some code that will be eliminated if BUILD.allRenderFn is false
* }
* ```
*
* `@app-data`, the module that `BUILD` is imported from, is an alias for the `@stencil/core/internal/app-data`, and is
* partially referenced by {@link STENCIL_APP_DATA_ID}. The `src/compiler/bundle/app-data-plugin.ts` references
* `STENCIL_APP_DATA_ID` uses it to replace these defaults with {@link BuildConditionals} that are derived from a
* Stencil project's contents (i.e. metadata from the components). This replacement happens at a Stencil project's
* compile time. Such code can be found at `src/compiler/app-core/app-data.ts`.
*/
export const BUILD: BuildConditionals = {
allRenderFn: false,
element: true,
event: true,
hasRenderFn: true,
hostListener: true,
hostListenerTargetWindow: true,
hostListenerTargetDocument: true,
hostListenerTargetBody: true,
hostListenerTargetParent: false,
hostListenerTarget: true,
member: true,
method: true,
mode: true,
observeAttribute: true,
prop: true,
propMutable: true,
reflect: true,
scoped: true,
shadowDom: true,
slot: true,
cssAnnotations: true,
state: true,
style: true,
formAssociated: false,
svg: true,
updatable: true,
vdomAttribute: true,
vdomXlink: true,
vdomClass: true,
vdomFunctional: true,
vdomKey: true,
vdomListener: true,
vdomRef: true,
vdomPropOrAttr: true,
vdomRender: true,
vdomStyle: true,
vdomText: true,
propChangeCallback: true,
taskQueue: true,
hotModuleReplacement: false,
isDebug: false,
isDev: false,
isTesting: false,
hydrateServerSide: false,
hydrateClientSide: false,
lifecycleDOMEvents: false,
lazyLoad: false,
profile: false,
slotRelocation: true,
// TODO(STENCIL-914): remove this option when `experimentalSlotFixes` is the default behavior
appendChildSlotFix: false,
// TODO(STENCIL-914): remove this option when `experimentalSlotFixes` is the default behavior
cloneNodeFix: false,
hydratedAttribute: false,
hydratedClass: true,
// TODO(STENCIL-1305): remove this option
scriptDataOpts: false,
// TODO(STENCIL-914): remove this option when `experimentalSlotFixes` is the default behavior
scopedSlotTextContentFix: false,
// TODO(STENCIL-854): Remove code related to legacy shadowDomShim field
shadowDomShim: false,
// TODO(STENCIL-914): remove this option when `experimentalSlotFixes` is the default behavior
slotChildNodesFix: false,
invisiblePrehydration: true,
propBoolean: true,
propNumber: true,
propString: true,
constructableCSS: true,
devTools: false,
shadowDelegatesFocus: true,
shadowSlotAssignmentManual: false,
initializeNextTick: false,
asyncLoading: true,
asyncQueue: false,
// TODO: deprecated in favour of `setTagTransformer` and `transformTag`. Remove in 5.0
transformTagName: false,
attachStyles: true,
// TODO(STENCIL-914): remove this option when `experimentalSlotFixes` is the default behavior
experimentalSlotFixes: false,
};
export const Env = {};
export const NAMESPACE = /* default */ 'app' as string;
================================================
FILE: src/app-globals/index.ts
================================================
export const globalScripts = /* default */ () => {
/**/
};
export const globalStyles = /* default */ '';
================================================
FILE: src/cli/check-version.ts
================================================
import { isFunction } from '@utils';
import type { ValidatedConfig } from '../declarations';
/**
* Retrieve a reference to the active `CompilerSystem`'s `checkVersion` function
* @param config the Stencil configuration associated with the currently compiled project
* @param currentVersion the Stencil compiler's version string
* @returns a reference to `checkVersion`, or `null` if one does not exist on the current `CompilerSystem`
*/
export const startCheckVersion = async (
config: ValidatedConfig,
currentVersion: string,
): Promise<(() => void) | null> => {
if (config.devMode && !config.flags.ci && !currentVersion.includes('-dev.') && isFunction(config.sys.checkVersion)) {
return config.sys.checkVersion(config.logger, currentVersion);
}
return null;
};
/**
* Print the results of running the provided `versionChecker`.
*
* Does not print if no `versionChecker` is provided.
*
* @param versionChecker the function to invoke.
*/
export const printCheckVersionResults = async (versionChecker: Promise<(() => void) | null>): Promise => {
if (versionChecker) {
const checkVersionResults = await versionChecker;
if (isFunction(checkVersionResults)) {
checkVersionResults();
}
}
};
================================================
FILE: src/cli/config-flags.ts
================================================
import type { LogLevel, TaskCommand } from '@stencil/core/declarations';
/**
* All the Boolean options supported by the Stencil CLI
*/
export const BOOLEAN_CLI_FLAGS = [
'build',
'cache',
'checkVersion',
'ci',
'compare',
'debug',
'dev',
'devtools',
'docs',
// @deprecated - integrated testing will be removed in Stencil v5. See https://github.com/stenciljs/core/issues/6584.
'e2e',
'es5',
'esm',
'help',
'log',
'open',
'prerender',
'prerenderExternal',
'prod',
'profile',
'serviceWorker',
// @deprecated - screenshot testing will be removed in Stencil v5. See https://github.com/stenciljs/core/issues/6584.
'screenshot',
'serve',
'skipNodeCheck',
// @deprecated - integrated testing will be removed in Stencil v5. See https://github.com/stenciljs/core/issues/6584.
'spec',
'ssr',
// @deprecated - screenshot testing will be removed in Stencil v5. See https://github.com/stenciljs/core/issues/6584.
'updateScreenshot',
'verbose',
'version',
'watch',
// @deprecated - all JEST CLI options below are only used by integrated testing, which will be removed in Stencil v5.
// See https://github.com/stenciljs/core/issues/6584.
// JEST CLI OPTIONS
'all',
'automock',
'bail',
// 'cache', Stencil already supports this argument
'changedFilesWithAncestor',
// 'ci', Stencil already supports this argument
'clearCache',
'clearMocks',
'collectCoverage',
'color',
'colors',
'coverage',
// 'debug', Stencil already supports this argument
'detectLeaks',
'detectOpenHandles',
'errorOnDeprecated',
'expand',
'findRelatedTests',
'forceExit',
'init',
'injectGlobals',
'json',
'lastCommit',
'listTests',
'logHeapUsage',
'noStackTrace',
'notify',
'onlyChanged',
'onlyFailures',
'passWithNoTests',
'resetMocks',
'resetModules',
'restoreMocks',
'runInBand',
'runTestsByPath',
'showConfig',
'silent',
'skipFilter',
'testLocationInResults',
'updateSnapshot',
'useStderr',
// 'verbose', Stencil already supports this argument
// 'version', Stencil already supports this argument
// 'watch', Stencil already supports this argument
'watchAll',
'watchman',
] as const;
/**
* All the Number options supported by the Stencil CLI
*/
export const NUMBER_CLI_FLAGS = [
'port',
// @deprecated - all JEST CLI args below are only used by integrated testing, which will be removed in Stencil v5.
// See https://github.com/stenciljs/core/issues/6584.
// JEST CLI ARGS
'maxConcurrency',
'testTimeout',
] as const;
/**
* All the String options supported by the Stencil CLI
*/
export const STRING_CLI_FLAGS = [
'address',
'config',
'docsApi',
'docsJson',
'emulate',
'root',
// @deprecated - screenshot testing will be removed in Stencil v5. See https://github.com/stenciljs/core/issues/6584.
'screenshotConnector',
// @deprecated - all JEST CLI args below are only used by integrated testing, which will be removed in Stencil v5.
// See https://github.com/stenciljs/core/issues/6584.
// JEST CLI ARGS
'cacheDirectory',
'changedSince',
'collectCoverageFrom',
// 'config', Stencil already supports this argument
'coverageDirectory',
'coverageThreshold',
'env',
'filter',
'globalSetup',
'globalTeardown',
'globals',
'haste',
'moduleNameMapper',
'notifyMode',
'outputFile',
'preset',
'prettierPath',
'resolver',
'rootDir',
'runner',
'testEnvironment',
'testEnvironmentOptions',
'testFailureExitCode',
'testNamePattern',
'testResultsProcessor',
'testRunner',
'testSequencer',
'testURL',
'timers',
'transform',
] as const;
// @deprecated - all entries below are JEST CLI args only used by integrated testing, which will be removed in Stencil v5.
// See https://github.com/stenciljs/core/issues/6584.
export const STRING_ARRAY_CLI_FLAGS = [
'collectCoverageOnlyFrom',
'coveragePathIgnorePatterns',
'coverageReporters',
'moduleDirectories',
'moduleFileExtensions',
'modulePathIgnorePatterns',
'modulePaths',
'projects',
'reporters',
'roots',
'selectProjects',
'setupFiles',
'setupFilesAfterEnv',
'snapshotSerializers',
'testMatch',
'testPathIgnorePatterns',
'testPathPattern',
'testRegex',
'transformIgnorePatterns',
'unmockedModulePathPatterns',
'watchPathIgnorePatterns',
] as const;
/**
* All the CLI arguments which may have string or number values
*
* `maxWorkers` is an argument which is used both by Stencil _and_ by Jest,
* which means that we need to support parsing both string and number values.
*/
export const STRING_NUMBER_CLI_FLAGS = ['maxWorkers'] as const;
/**
* All the CLI arguments which may have boolean or string values.
*/
export const BOOLEAN_STRING_CLI_FLAGS = [
/**
* `headless` is an argument passed through to Puppeteer (which is passed to Chrome) for end-to-end testing.
*
* {@see https://developer.chrome.com/blog/chrome-headless-shell/}
*/
'headless',
/**
* `stats` is an argument that can optionally accept a file path where stats should be written.
* When used as a boolean (--stats), it defaults to 'stencil-stats.json'.
* When used with a path (--stats dist/stats.json), it writes to that path.
*/
'stats',
] as const;
/**
* All the LogLevel-type options supported by the Stencil CLI
*
* This is a bit silly since there's only one such argument atm,
* but this approach lets us make sure that we're handling all
* our arguments in a type-safe way.
*/
export const LOG_LEVEL_CLI_FLAGS = ['logLevel'] as const;
/**
* A type which gives the members of a `ReadonlyArray` as
* an enum-like type which can be used for e.g. keys in a `Record`
* (as in the `AliasMap` type below)
*/
type ArrayValuesAsUnion> = T[number];
export type BooleanCLIFlag = ArrayValuesAsUnion;
export type StringCLIFlag = ArrayValuesAsUnion;
export type StringArrayCLIFlag = ArrayValuesAsUnion;
export type NumberCLIFlag = ArrayValuesAsUnion;
export type StringNumberCLIFlag = ArrayValuesAsUnion;
export type BooleanStringCLIFlag = ArrayValuesAsUnion;
export type LogCLIFlag = ArrayValuesAsUnion;
export type KnownCLIFlag =
| BooleanCLIFlag
| StringCLIFlag
| StringArrayCLIFlag
| NumberCLIFlag
| StringNumberCLIFlag
| BooleanStringCLIFlag
| LogCLIFlag;
type AliasMap = Partial>;
/**
* For a small subset of CLI options we support a short alias e.g. `'h'` for `'help'`
*/
export const CLI_FLAG_ALIASES: AliasMap = {
c: 'config',
h: 'help',
p: 'port',
v: 'version',
// JEST SPECIFIC CLI FLAGS
// these are defined in
// https://github.com/facebook/jest/blob/4156f86/packages/jest-cli/src/args.ts
b: 'bail',
e: 'expand',
f: 'onlyFailures',
i: 'runInBand',
o: 'onlyChanged',
t: 'testNamePattern',
u: 'updateSnapshot',
w: 'maxWorkers',
};
/**
* A regular expression which can be used to match a CLI flag for one of our
* short aliases.
*/
export const CLI_FLAG_REGEX = new RegExp(`^-[chpvbewofitu]{1}$`);
/**
* Given two types `K` and `T` where `K` extends `ReadonlyArray`,
* construct a type which maps the strings in `K` as keys to values of type `T`.
*
* Because we use types derived this way to construct an interface (`ConfigFlags`)
* for which we want optional keys, we make all the properties optional (w/ `'?'`)
* and possibly null.
*/
type ObjectFromKeys, T> = {
[key in K[number]]?: T | null;
};
/**
* Type containing the possible Boolean configuration flags, to be included
* in ConfigFlags, below
*/
type BooleanConfigFlags = ObjectFromKeys;
/**
* Type containing the possible String configuration flags, to be included
* in ConfigFlags, below
*/
type StringConfigFlags = ObjectFromKeys;
/**
* Type containing the possible String Array configuration flags. This is
* one of the 'constituent types' for `ConfigFlags`.
*/
type StringArrayConfigFlags = ObjectFromKeys;
/**
* Type containing the possible numeric configuration flags, to be included
* in ConfigFlags, below
*/
type NumberConfigFlags = ObjectFromKeys;
/**
* Type containing the configuration flags which may be set to either string
* or number values.
*/
type StringNumberConfigFlags = ObjectFromKeys;
/**
* Type containing the configuration flags which may be set to either string
* or boolean values.
*/
type BooleanStringConfigFlags = ObjectFromKeys;
/**
* Type containing the possible LogLevel configuration flags, to be included
* in ConfigFlags, below
*/
type LogLevelFlags = ObjectFromKeys;
/**
* The configuration flags which can be set by the user on the command line.
* This interface captures both known arguments (which are enumerated and then
* parsed according to their types) and unknown arguments which the user may
* pass at the CLI.
*
* Note that this interface is constructed by extending `BooleanConfigFlags`,
* `StringConfigFlags`, etc. These types are in turn constructed from types
* extending `ReadonlyArray` which we declare in another module. This
* allows us to record our known CLI arguments in one place, using a
* `ReadonlyArray` to get both a type-level representation of what CLI
* options we support and a runtime list of strings which can be used to match
* on actual flags passed by the user.
*/
export interface ConfigFlags
extends BooleanConfigFlags,
StringConfigFlags,
StringArrayConfigFlags,
NumberConfigFlags,
StringNumberConfigFlags,
BooleanStringConfigFlags,
LogLevelFlags {
task: TaskCommand | null;
args: string[];
knownArgs: string[];
unknownArgs: string[];
}
/**
* Helper function for initializing a `ConfigFlags` object. Provide any overrides
* for default values and off you go!
*
* @param init an object with any overrides for default values
* @returns a complete CLI flag object
*/
export const createConfigFlags = (init: Partial = {}): ConfigFlags => {
const flags: ConfigFlags = {
task: null,
args: [],
knownArgs: [],
unknownArgs: [],
...init,
};
return flags;
};
================================================
FILE: src/cli/find-config.ts
================================================
import { buildError, isString, normalizePath, result } from '@utils';
import type { CompilerSystem, Diagnostic } from '../declarations';
/**
* An object containing the {@link CompilerSystem} used to find the configuration file, as well as the location on disk
* to search for a Stencil configuration
*/
export type FindConfigOptions = {
sys: CompilerSystem;
configPath?: string | null;
};
/**
* The results of attempting to find a Stencil configuration file on disk
*/
export type FindConfigResults = {
configPath: string;
rootDir: string;
};
/**
* Attempt to find a Stencil configuration file on the file system
* @param opts the options needed to find the configuration file
* @returns the results of attempting to find a configuration file on disk
*/
export const findConfig = async (opts: FindConfigOptions): Promise> => {
const sys = opts.sys;
const cwd = sys.getCurrentDirectory();
const rootDir = normalizePath(cwd);
let configPath = opts.configPath;
if (isString(configPath)) {
if (!sys.platformPath.isAbsolute(configPath)) {
// passed in a custom stencil config location,
// but it's relative, so prefix the cwd
configPath = normalizePath(sys.platformPath.join(cwd, configPath));
} else {
// config path already an absolute path, we're good here
configPath = normalizePath(configPath);
}
} else {
// nothing was passed in, use the current working directory
configPath = rootDir;
}
const results: FindConfigResults = {
configPath,
rootDir: normalizePath(cwd),
};
const stat = await sys.stat(configPath);
if (stat.error) {
const diagnostics: Diagnostic[] = [];
const diagnostic = buildError(diagnostics);
diagnostic.absFilePath = configPath;
diagnostic.header = `Invalid config path`;
diagnostic.messageText = `Config path "${configPath}" not found`;
return result.err(diagnostics);
}
if (stat.isFile) {
results.configPath = configPath;
results.rootDir = sys.platformPath.dirname(configPath);
} else if (stat.isDirectory) {
// this is only a directory, so let's make some assumptions
for (const configName of ['stencil.config.ts', 'stencil.config.js']) {
const testConfigFilePath = sys.platformPath.join(configPath, configName);
const stat = await sys.stat(testConfigFilePath);
if (stat.isFile) {
results.configPath = testConfigFilePath;
results.rootDir = sys.platformPath.dirname(testConfigFilePath);
break;
}
}
}
return result.ok(results);
};
================================================
FILE: src/cli/index.ts
================================================
export { BOOLEAN_CLI_FLAGS, ConfigFlags } from './config-flags';
export { parseFlags } from './parse-flags';
export { run, runTask } from './run';
================================================
FILE: src/cli/ionic-config.ts
================================================
import type * as d from '../declarations';
import { readJson, UUID_REGEX, uuidv4 } from './telemetry/helpers';
export const isTest = () => process.env.JEST_WORKER_ID !== undefined;
export const defaultConfig = (sys: d.CompilerSystem) =>
sys.resolvePath(`${sys.homeDir()}/.ionic/${isTest() ? 'tmp-config.json' : 'config.json'}`);
export const defaultConfigDirectory = (sys: d.CompilerSystem) => sys.resolvePath(`${sys.homeDir()}/.ionic`);
/**
* Reads an Ionic configuration file from disk, parses it, and performs any necessary corrections to it if certain
* values are deemed to be malformed
* @param sys The system where the command is invoked
* @returns the config read from disk that has been potentially been updated
*/
export async function readConfig(sys: d.CompilerSystem): Promise {
let config: d.TelemetryConfig = await readJson(sys, defaultConfig(sys));
if (!config) {
config = {
'tokens.telemetry': uuidv4(),
'telemetry.stencil': true,
};
await writeConfig(sys, config);
} else if (!config['tokens.telemetry'] || !UUID_REGEX.test(config['tokens.telemetry'])) {
const newUuid = uuidv4();
await writeConfig(sys, { ...config, 'tokens.telemetry': newUuid });
config['tokens.telemetry'] = newUuid;
}
return config;
}
/**
* Writes an Ionic configuration file to disk.
* @param sys The system where the command is invoked
* @param config The config passed into the Stencil command
* @returns boolean If the command was successful
*/
export async function writeConfig(sys: d.CompilerSystem, config: d.TelemetryConfig): Promise {
let result = false;
try {
await sys.createDir(defaultConfigDirectory(sys), { recursive: true });
await sys.writeFile(defaultConfig(sys), JSON.stringify(config, null, 2));
result = true;
} catch (error) {
console.error(`Stencil Telemetry: couldn't write configuration file to ${defaultConfig(sys)} - ${error}.`);
}
return result;
}
/**
* Update a subset of the Ionic config.
* @param sys The system where the command is invoked
* @param newOptions The new options to save
* @returns boolean If the command was successful
*/
export async function updateConfig(sys: d.CompilerSystem, newOptions: d.TelemetryConfig): Promise {
const config = await readConfig(sys);
return await writeConfig(sys, Object.assign(config, newOptions));
}
================================================
FILE: src/cli/load-compiler.ts
================================================
import type { CompilerSystem } from '../declarations';
export const loadCoreCompiler = async (sys: CompilerSystem): Promise => {
return await sys.dynamicImport!(sys.getCompilerExecutingPath());
};
export type CoreCompiler = typeof import('@stencil/core/compiler');
================================================
FILE: src/cli/logs.ts
================================================
import type { CompilerSystem, Logger, TaskCommand, ValidatedConfig } from '../declarations';
import type { ConfigFlags } from './config-flags';
import type { CoreCompiler } from './load-compiler';
/**
* Log the name of this package (`@stencil/core`) to an output stream
*
* The output stream is determined by the {@link Logger} instance that is provided as an argument to this function
*
* The name of the package may not be logged, by design, for certain `task` types and logging levels
*
* @param logger the logging entity to use to output the name of the package
* @param task the current task
*/
export const startupLog = (logger: Logger, task: TaskCommand): void => {
if (task === 'info' || task === 'serve' || task === 'version') {
return;
}
logger.info(logger.cyan(`@stencil/core`));
};
/**
* Log this package's version to an output stream
*
* The output stream is determined by the {@link Logger} instance that is provided as an argument to this function
*
* The package version may not be logged, by design, for certain `task` types and logging levels
*
* @param logger the logging entity to use for output
* @param task the current task
* @param coreCompiler the compiler instance to derive version information from
*/
export const startupLogVersion = (logger: Logger, task: TaskCommand, coreCompiler: CoreCompiler): void => {
if (task === 'info' || task === 'serve' || task === 'version') {
return;
}
const isDevBuild = coreCompiler.version.includes('-dev.');
let startupMsg: string;
if (isDevBuild) {
startupMsg = logger.yellow(`[LOCAL DEV] v${coreCompiler.version}`);
} else {
startupMsg = logger.cyan(`v${coreCompiler.version}`);
}
startupMsg += logger.emoji(' ' + coreCompiler.vermoji);
logger.info(startupMsg);
};
/**
* Log details from a {@link CompilerSystem} used by Stencil to an output stream
*
* The output stream is determined by the {@link Logger} instance that is provided as an argument to this function
*
* @param sys the `CompilerSystem` to report details on
* @param logger the logging entity to use for output
* @param flags user set flags for the current invocation of Stencil
* @param coreCompiler the compiler instance being used for this invocation of Stencil
*/
export const loadedCompilerLog = (
sys: CompilerSystem,
logger: Logger,
flags: ConfigFlags,
coreCompiler: CoreCompiler,
): void => {
const sysDetails = sys.details;
const runtimeInfo = `${sys.name} ${sys.version}`;
const platformInfo = sysDetails
? `${sysDetails.platform}, ${sysDetails.cpuModel}`
: `Unknown Platform, Unknown CPU Model`;
const statsInfo = sysDetails
? `cpus: ${sys.hardwareConcurrency}, freemem: ${Math.round(
sysDetails.freemem() / 1000000,
)}MB, totalmem: ${Math.round(sysDetails.totalmem / 1000000)}MB`
: 'Unknown CPU Core Count, Unknown Memory';
if (logger.getLevel() === 'debug') {
logger.debug(runtimeInfo);
logger.debug(platformInfo);
logger.debug(statsInfo);
logger.debug(`compiler: ${sys.getCompilerExecutingPath()}`);
logger.debug(`build: ${coreCompiler.buildId}`);
} else if (flags.ci) {
logger.info(runtimeInfo);
logger.info(platformInfo);
logger.info(statsInfo);
}
};
/**
* Log various warnings to an output stream
*
* The output stream is determined by the {@link Logger} instance attached to the `config` argument to this function
*
* @param coreCompiler the compiler instance being used for this invocation of Stencil
* @param config a validated configuration object to be used for this run of Stencil
*/
export const startupCompilerLog = (coreCompiler: CoreCompiler, config: ValidatedConfig) => {
if (config.suppressLogs === true) {
return;
}
const { logger } = config;
const isDebug = logger.getLevel() === 'debug';
const isPrerelease = coreCompiler.version.includes('-');
const isDevBuild = coreCompiler.version.includes('-dev.');
if (isPrerelease && !isDevBuild) {
logger.warn(
logger.yellow(
`This is a prerelease build, undocumented changes might happen at any time. Technical support is not available for prereleases, but any assistance testing is appreciated.`,
),
);
}
if (config.devMode && !isDebug) {
if (config.buildEs5) {
logger.warn(
`Generating ES5 during development is a very task expensive, initial and incremental builds will be much slower. Drop the '--es5' flag and use a modern browser for development.`,
);
}
if (!config.enableCache) {
logger.warn(`Disabling cache during development will slow down incremental builds.`);
}
}
};
================================================
FILE: src/cli/parse-flags.ts
================================================
import { readOnlyArrayHasStringMember, toCamelCase } from '@utils';
import { LOG_LEVELS, LogLevel, TaskCommand } from '../declarations';
import {
BOOLEAN_CLI_FLAGS,
BOOLEAN_STRING_CLI_FLAGS,
CLI_FLAG_ALIASES,
CLI_FLAG_REGEX,
ConfigFlags,
createConfigFlags,
LOG_LEVEL_CLI_FLAGS,
NUMBER_CLI_FLAGS,
STRING_ARRAY_CLI_FLAGS,
STRING_CLI_FLAGS,
STRING_NUMBER_CLI_FLAGS,
} from './config-flags';
/**
* Parse command line arguments into a structured `ConfigFlags` object
*
* @param args an array of CLI flags
* @returns a structured ConfigFlags object
*/
export const parseFlags = (args: string[]): ConfigFlags => {
const flags: ConfigFlags = createConfigFlags();
// cmd line has more priority over npm scripts cmd
flags.args = Array.isArray(args) ? args.slice() : [];
if (flags.args.length > 0 && flags.args[0] && !flags.args[0].startsWith('-')) {
flags.task = flags.args[0] as TaskCommand;
// if the first argument was a "task" (like `build`, `test`, etc) then
// we go on to parse the _rest_ of the CLI args
parseArgs(flags, args.slice(1));
} else {
// we didn't find a leading flag, so we should just parse them all
parseArgs(flags, flags.args);
}
if (flags.task != null) {
const i = flags.args.indexOf(flags.task);
if (i > -1) {
flags.args.splice(i, 1);
}
}
return flags;
};
/**
* Parse the supported command line flags which are enumerated in the
* `config-flags` module. Handles leading dashes on arguments, aliases that are
* defined for a small number of arguments, and parsing values for non-boolean
* arguments (e.g. port number for the dev server).
*
* This parses the following grammar:
*
* CLIArguments → ""
* | CLITerm ( " " CLITerm )* ;
* CLITerm → EqualsArg
* | AliasEqualsArg
* | AliasArg
* | NegativeDashArg
* | NegativeArg
* | SimpleArg ;
* EqualsArg → "--" ArgName "=" CLIValue ;
* AliasEqualsArg → "-" AliasName "=" CLIValue ;
* AliasArg → "-" AliasName ( " " CLIValue )? ;
* NegativeDashArg → "--no-" ArgName ;
* NegativeArg → "--no" ArgName ;
* SimpleArg → "--" ArgName ( " " CLIValue )? ;
* ArgName → /^[a-zA-Z-]+$/ ;
* AliasName → /^[a-z]{1}$/ ;
* CLIValue → '"' /^[a-zA-Z0-9]+$/ '"'
* | /^[a-zA-Z0-9]+$/ ;
*
* There are additional constraints (not shown in the grammar for brevity's sake)
* on the type of `CLIValue` which will be associated with a particular argument.
* We enforce this by declaring lists of boolean, string, etc arguments and
* checking the types of values before setting them.
*
* We don't need to turn the list of CLI arg tokens into any kind of
* intermediate representation since we aren't concerned with doing anything
* other than setting the correct values on our ConfigFlags object. So we just
* parse the array of string arguments using a recursive-descent approach
* (which is not very deep since our grammar is pretty simple) and make the
* modifications we need to make to the {@link ConfigFlags} object as we go.
*
* @param flags a ConfigFlags object to which parsed arguments will be added
* @param args an array of command-line arguments to parse
*/
const parseArgs = (flags: ConfigFlags, args: string[]) => {
const argsCopy = args.concat();
while (argsCopy.length > 0) {
// there are still unprocessed args to deal with
parseCLITerm(flags, argsCopy);
}
};
/**
* Given an array of CLI arguments, parse it and perform a series of side
* effects (setting values on the provided `ConfigFlags` object).
*
* @param flags a {@link ConfigFlags} object which is updated as we parse the CLI
* arguments
* @param args a list of args to work through. This function (and some functions
* it calls) calls `Array.prototype.shift` to get the next argument to look at,
* so this parameter will be modified.
*/
const parseCLITerm = (flags: ConfigFlags, args: string[]) => {
// pull off the first arg from the argument array
const arg = args.shift();
// array is empty, we're done!
if (arg === undefined) return;
// capture whether this is a special case of a negated boolean or boolean-string before we start to test each case
const isNegatedBoolean =
!readOnlyArrayHasStringMember(BOOLEAN_CLI_FLAGS, normalizeFlagName(arg)) &&
readOnlyArrayHasStringMember(BOOLEAN_CLI_FLAGS, normalizeNegativeFlagName(arg));
const isNegatedBooleanOrString =
!readOnlyArrayHasStringMember(BOOLEAN_STRING_CLI_FLAGS, normalizeFlagName(arg)) &&
readOnlyArrayHasStringMember(BOOLEAN_STRING_CLI_FLAGS, normalizeNegativeFlagName(arg));
// EqualsArg → "--" ArgName "=" CLIValue ;
if (arg.startsWith('--') && arg.includes('=')) {
// we're dealing with an EqualsArg, we have a special helper for that
const [originalArg, value] = parseEqualsArg(arg);
setCLIArg(flags, arg.split('=')[0], normalizeFlagName(originalArg), value);
}
// AliasEqualsArg → "-" AliasName "=" CLIValue ;
else if (arg.startsWith('-') && arg.includes('=')) {
// we're dealing with an AliasEqualsArg, we have a special helper for that
const [originalArg, value] = parseEqualsArg(arg);
setCLIArg(flags, desugarRawAlias(originalArg), normalizeFlagName(originalArg), value);
}
// AliasArg → "-" AliasName ( " " CLIValue )? ;
else if (CLI_FLAG_REGEX.test(arg)) {
// this is a short alias, like `-c` for Config
setCLIArg(flags, desugarRawAlias(arg), normalizeFlagName(arg), parseCLIValue(args));
}
// NegativeDashArg → "--no-" ArgName ;
else if (arg.startsWith('--no-') && arg.length > '--no-'.length) {
// this is a `NegativeDashArg` term, so we need to normalize the negative
// flag name and then set an appropriate value
const normalized = normalizeNegativeFlagName(arg);
setCLIArg(flags, arg, normalized, '');
}
// NegativeArg → "--no" ArgName ;
else if (arg.startsWith('--no') && (isNegatedBoolean || isNegatedBooleanOrString)) {
// possibly dealing with a `NegativeArg` here. There is a little ambiguity
// here because we have arguments that already begin with `no` like
// `notify`, so we need to test if a normalized form of the raw argument is
// a valid and supported boolean flag.
setCLIArg(flags, arg, normalizeNegativeFlagName(arg), '');
}
// SimpleArg → "--" ArgName ( " " CLIValue )? ;
else if (arg.startsWith('--') && arg.length > '--'.length) {
setCLIArg(flags, arg, normalizeFlagName(arg), parseCLIValue(args));
} else {
// if we get here then `arg` is not an argument in our list of supported
// arguments. This doesn't necessarily mean we want to report an error or
// anything though! Instead, with unknown / unrecognized arguments we want
// to stick them into the `unknownArgs` array, which is used when we pass
// CLI args to Jest, for instance.
flags.unknownArgs.push(arg);
}
};
/**
* Normalize a 'negative' flag name, just to do a little pre-processing before
* we pass it to {@link setCLIArg}.
*
* @param flagName the flag name to normalize
* @returns a normalized flag name
*/
const normalizeNegativeFlagName = (flagName: string): string => {
const trimmed = flagName.replace(/^--no[-]?/, '');
return normalizeFlagName(trimmed.charAt(0).toLowerCase() + trimmed.slice(1));
};
/**
* Normalize a flag name by:
*
* - replacing any leading dashes (`--foo` -> `foo`)
* - converting `dash-case` to camelCase (if necessary)
*
* Normalizing in this context basically means converting the various
* supported flag spelling variants to the variant defined in our lists of
* supported arguments (e.g. BOOLEAN_CLI_FLAGS, etc). So, for instance,
* `--log-level` should be converted to `logLevel`.
*
* @param flagName the flag name to normalize
* @returns a normalized flag name
*
*/
const normalizeFlagName = (flagName: string): string => {
const trimmed = flagName.replace(/^-+/, '');
return trimmed.includes('-') ? toCamelCase(trimmed) : trimmed;
};
/**
* Set a value on a provided {@link ConfigFlags} object, given an argument
* name and a raw string value. This function dispatches to other functions
* which make sure that the string value can be properly parsed into a JS
* runtime value of the right type (e.g. number, string, etc).
*
* @throws if a value cannot be parsed to the right type for a given flag
* @param flags a {@link ConfigFlags} object
* @param rawArg the raw argument name matched by the parser
* @param normalizedArg an argument with leading control characters (`--`,
* `--no-`, etc) removed
* @param value the raw value to be set onto the config flags object
*/
const setCLIArg = (flags: ConfigFlags, rawArg: string, normalizedArg: string, value: CLIValueResult) => {
normalizedArg = desugarAlias(normalizedArg);
// We're setting a boolean!
if (readOnlyArrayHasStringMember(BOOLEAN_CLI_FLAGS, normalizedArg)) {
const parsed =
typeof value === 'string'
? // check if the value is `'true'`
value === 'true'
: // no value was supplied, default to true
true;
flags[normalizedArg] = parsed;
flags.knownArgs.push(rawArg);
if (typeof value === 'string' && value !== '') {
flags.knownArgs.push(value);
}
}
// We're setting a string!
else if (readOnlyArrayHasStringMember(STRING_CLI_FLAGS, normalizedArg)) {
if (typeof value === 'string') {
flags[normalizedArg] = value;
flags.knownArgs.push(rawArg);
flags.knownArgs.push(value);
} else {
throwCLIParsingError(rawArg, 'expected a string argument but received nothing');
}
}
// We're setting a string, but it's one where the user can pass multiple values,
// like `--reporters="default" --reporters="jest-junit"`
else if (readOnlyArrayHasStringMember(STRING_ARRAY_CLI_FLAGS, normalizedArg)) {
if (typeof value === 'string') {
if (!Array.isArray(flags[normalizedArg])) {
flags[normalizedArg] = [];
}
const targetArray = flags[normalizedArg];
// this is irritating, but TS doesn't know that the `!Array.isArray`
// check above guarantees we have an array to work with here, and it
// doesn't want to narrow the type of `flags[normalizedArg]`, so we need
// to grab a reference to that array and then `Array.isArray` that. Bah!
if (Array.isArray(targetArray)) {
targetArray.push(value);
flags.knownArgs.push(rawArg);
flags.knownArgs.push(value);
}
} else {
throwCLIParsingError(rawArg, 'expected a string argument but received nothing');
}
}
// We're setting a number!
else if (readOnlyArrayHasStringMember(NUMBER_CLI_FLAGS, normalizedArg)) {
if (typeof value === 'string') {
const parsed = parseInt(value, 10);
if (isNaN(parsed)) {
throwNumberParsingError(rawArg, value);
} else {
flags[normalizedArg] = parsed;
flags.knownArgs.push(rawArg);
flags.knownArgs.push(value);
}
} else {
throwCLIParsingError(rawArg, 'expected a number argument but received nothing');
}
}
// We're setting a value which could be either a string _or_ a number
else if (readOnlyArrayHasStringMember(STRING_NUMBER_CLI_FLAGS, normalizedArg)) {
if (typeof value === 'string') {
if (CLI_ARG_STRING_REGEX.test(value)) {
// if it matches the regex we treat it like a string
flags[normalizedArg] = value;
} else {
const parsed = Number(value);
if (isNaN(parsed)) {
// parsing didn't go so well, we gotta get out of here
// this is unlikely given our regex guard above
// but hey, this is ultimately JS so let's be safe
throwNumberParsingError(rawArg, value);
} else {
flags[normalizedArg] = parsed;
}
}
flags.knownArgs.push(rawArg);
flags.knownArgs.push(value);
} else {
throwCLIParsingError(rawArg, 'expected a string or a number but received nothing');
}
}
// We're setting a value which could be either a boolean _or_ a string
else if (readOnlyArrayHasStringMember(BOOLEAN_STRING_CLI_FLAGS, normalizedArg)) {
const derivedValue =
typeof value === 'string'
? value
? value // use the supplied value if it's a non-empty string
: false // otherwise, default to false for the empty string
: true; // no value was supplied, default to true
flags[normalizedArg] = derivedValue;
flags.knownArgs.push(rawArg);
if (typeof derivedValue === 'string' && derivedValue) {
flags.knownArgs.push(derivedValue);
}
}
// We're setting the log level, which can only be a set of specific string values
else if (readOnlyArrayHasStringMember(LOG_LEVEL_CLI_FLAGS, normalizedArg)) {
if (typeof value === 'string') {
if (isLogLevel(value)) {
flags[normalizedArg] = value;
flags.knownArgs.push(rawArg);
flags.knownArgs.push(value);
} else {
throwCLIParsingError(rawArg, `expected to receive a valid log level but received "${String(value)}"`);
}
} else {
throwCLIParsingError(rawArg, 'expected to receive a valid log level but received nothing');
}
} else {
// we haven't found this flag in any of our lists of arguments, so we
// should put it in our list of unknown arguments
flags.unknownArgs.push(rawArg);
if (typeof value === 'string') {
flags.unknownArgs.push(value);
}
}
};
/**
* We use this regular expression to detect CLI parameters which
* should be parsed as string values (as opposed to numbers) for
* the argument types for which we support both a string and a
* number value.
*
* The regex tests for the presence of at least one character which is
* _not_ a digit (`\d`), a period (`\.`), or one of the characters `"e"`,
* `"E"`, `"+"`, or `"-"` (the latter four characters are necessary to
* support the admittedly unlikely use of scientific notation, like `"4e+0"`
* for `4`).
*
* Thus we'll match a string like `"50%"`, but not a string like `"50"` or
* `"5.0"`. If it matches a given string we conclude that the string should
* be parsed as a string literal, rather than using `Number` to convert it
* to a number.
*/
const CLI_ARG_STRING_REGEX = /[^\d\.Ee\+\-]+/g;
export const Empty = Symbol('Empty');
/**
* The result of trying to parse a CLI arg. This will be a `string` if a
* well-formed value is present, or `Empty` to indicate that nothing was matched
* or that the input was malformed.
*/
type CLIValueResult = string | typeof Empty;
/**
* A little helper which tries to parse a CLI value (as opposed to a flag) off
* of the argument array.
*
* We support a variety of different argument formats for flags (as opposed to
* values), but all of them start with `-`, so we can check the first character
* to test whether the next token in our array of CLI arguments is a flag name
* or a value.
*
* @param args an array of CLI args
* @returns either a string result or an Empty sentinel
*/
const parseCLIValue = (args: string[]): CLIValueResult => {
// it's possible the arguments array is empty, if so, return empty
if (args[0] === undefined) {
return Empty;
}
// all we're concerned with here is that it does not start with `"-"`,
// which would indicate it should be parsed as a CLI flag and not a value.
if (!args[0].startsWith('-')) {
// It's not a flag, so we return the value and defer any specific parsing
// until later on.
const value = args.shift();
if (typeof value === 'string') {
return value;
}
}
return Empty;
};
/**
* Parse an 'equals' argument, which is a CLI argument-value pair in the
* format `--foobar=12` (as opposed to a space-separated format like
* `--foobar 12`).
*
* To parse this we split on the `=`, returning the first part as the argument
* name and the second part as the value. We join the value on `"="` in case
* there is another `"="` in the argument.
*
* This function is safe to call with any arg, and can therefore be used as
* an argument 'normalizer'. If CLI argument is not an 'equals' argument then
* the return value will be a tuple of the original argument and an empty
* string `""` for the value.
*
* In code terms, if you do:
*
* ```ts
* const [arg, value] = parseEqualsArg("--myArgument")
* ```
*
* Then `arg` will be `"--myArgument"` and `value` will be `""`, whereas if
* you do:
*
*
* ```ts
* const [arg, value] = parseEqualsArg("--myArgument=myValue")
* ```
*
* Then `arg` will be `"--myArgument"` and `value` will be `"myValue"`.
*
* @param arg the arg in question
* @returns a tuple containing the arg name and the value (if present)
*/
export const parseEqualsArg = (arg: string): [string, CLIValueResult] => {
const [originalArg, ...splitSections] = arg.split('=');
const value = splitSections.join('=');
return [originalArg, value === '' ? Empty : value];
};
/**
* Small helper for getting type-system-level assurance that a `string` can be
* narrowed to a `LogLevel`
*
* @param maybeLogLevel the string to check
* @returns whether this is a `LogLevel`
*/
const isLogLevel = (maybeLogLevel: string): maybeLogLevel is LogLevel =>
readOnlyArrayHasStringMember(LOG_LEVELS, maybeLogLevel);
/**
* A little helper for constructing and throwing an error message with info
* about what went wrong
*
* @param flag the flag which encountered the error
* @param message a message specific to the error which was encountered
*/
const throwCLIParsingError = (flag: string, message: string) => {
throw new Error(`when parsing CLI flag "${flag}": ${message}`);
};
/**
* Throw a specific error for the situation where we ran into an issue parsing
* a number.
*
* @param flag the flag for which we encountered the issue
* @param value what we were trying to parse
*/
const throwNumberParsingError = (flag: string, value: string) => {
throwCLIParsingError(flag, `expected a number but received "${value}"`);
};
/**
* A little helper to 'desugar' a flag alias, meaning expand it to its full
* name. For instance, the alias `"c"` will desugar to `"config"`.
*
* If no expansion is found for the possible alias we just return the passed
* string unmodified.
*
* @param maybeAlias a string which _could_ be an alias to a full flag name
* @returns the full aliased flag name, if found, or the passed string if not
*/
const desugarAlias = (maybeAlias: string): string => {
const possiblyDesugared = CLI_FLAG_ALIASES[maybeAlias];
if (typeof possiblyDesugared === 'string') {
return possiblyDesugared;
}
return maybeAlias;
};
/**
* Desugar a 'raw' alias (with a leading dash) and return an equivalent,
* desugared argument.
*
* For instance, passing `"-c` will return `"--config"`.
*
* The reason we'd like to do this is not so much for our own code, but so that
* we can transform an alias like `"-u"` to `"--updateSnapshot"` in order to
* pass it along to Jest.
*
* @param rawAlias a CLI flag alias as found on the command line (like `"-c"`)
* @returns an equivalent full command (like `"--config"`)
*/
const desugarRawAlias = (rawAlias: string): string => '--' + desugarAlias(normalizeFlagName(rawAlias));
================================================
FILE: src/cli/public.ts
================================================
import type { CliInitOptions, Config, Logger, TaskCommand } from '@stencil/core/internal';
import type { ConfigFlags } from './config-flags';
/**
* Runs the CLI with the given options. This is used by Stencil's default `bin/stencil` file,
* but can be used externally too.
* @param init a set of initialization options needed to run Stencil from its CLI
* @returns an empty promise
*/
export declare function run(init: CliInitOptions): Promise;
/**
* Run individual CLI tasks.
* @param coreCompiler The core Stencil compiler to be used. The `run()` method handles loading the core compiler, however, `runTask()` must be passed it.
* @param config Assumes the config has already been validated and has the "sys" and "logger" properties.
* @param task The task command to run, such as `build`.
* @returns an empty promise
*/
export declare function runTask(coreCompiler: any, config: Config, task: TaskCommand): Promise;
export declare function parseFlags(args: string[]): ConfigFlags;
export { Config, ConfigFlags, Logger, TaskCommand };
================================================
FILE: src/cli/run.ts
================================================
import { hasError, isFunction, result, shouldIgnoreError } from '@utils';
import type * as d from '../declarations';
import { ValidatedConfig } from '../declarations';
import { createConfigFlags } from './config-flags';
import { findConfig } from './find-config';
import { CoreCompiler, loadCoreCompiler } from './load-compiler';
import { loadedCompilerLog, startupLog, startupLogVersion } from './logs';
import { parseFlags } from './parse-flags';
import { taskBuild } from './task-build';
import { taskDocs } from './task-docs';
import { taskGenerate } from './task-generate';
import { taskHelp } from './task-help';
import { taskInfo } from './task-info';
import { taskPrerender } from './task-prerender';
import { taskServe } from './task-serve';
import { taskTelemetry } from './task-telemetry';
import { taskTest } from './task-test';
import { telemetryAction } from './telemetry/telemetry';
/**
* Main entry point for the Stencil CLI
*
* Take care of parsing CLI arguments, initializing various components needed
* by the rest of the program, and kicking off the correct task (build, test,
* etc).
*
* @param init initial CLI options
* @returns an empty promise
*/
export const run = async (init: d.CliInitOptions) => {
const { args, logger, sys } = init;
try {
const flags = parseFlags(args);
const task = flags.task;
if (flags.debug || flags.verbose) {
logger.setLevel('debug');
}
if (flags.ci) {
logger.enableColors(false);
}
if (isFunction(sys.applyGlobalPatch)) {
sys.applyGlobalPatch(sys.getCurrentDirectory());
}
if ((task && task === 'version') || flags.version) {
// we need to load the compiler here to get the version, but we don't
// want to load it in the case that we're going to just log the help
// message and then exit below (if there's no `task` defined) so we load
// it just within our `if` scope here.
const coreCompiler = await loadCoreCompiler(sys);
console.log(coreCompiler.version);
return;
}
if (!task || task === 'help' || flags.help) {
await taskHelp(createConfigFlags({ task: 'help', args }), logger, sys);
return;
}
startupLog(logger, task);
const findConfigResults = await findConfig({ sys, configPath: flags.config });
if (findConfigResults.isErr) {
logger.printDiagnostics(findConfigResults.value);
return sys.exit(1);
}
const coreCompiler = await loadCoreCompiler(sys);
startupLogVersion(logger, task, coreCompiler);
loadedCompilerLog(sys, logger, flags, coreCompiler);
if (task === 'info') {
taskInfo(coreCompiler, sys, logger);
return;
}
const foundConfig = result.unwrap(findConfigResults);
const validated = await coreCompiler.loadConfig({
config: {
flags,
},
configPath: foundConfig.configPath,
logger,
sys,
});
if (validated.diagnostics.length > 0) {
logger.printDiagnostics(validated.diagnostics);
if (hasError(validated.diagnostics)) {
return sys.exit(1);
}
}
if (isFunction(sys.applyGlobalPatch)) {
sys.applyGlobalPatch(validated.config.rootDir);
}
await telemetryAction(sys, validated.config, coreCompiler, async () => {
await runTask(coreCompiler, validated.config, task, sys);
});
} catch (e) {
if (!shouldIgnoreError(e)) {
const details = `${logger.getLevel() === 'debug' && e instanceof Error ? e.stack : ''}`;
logger.error(`uncaught cli error: ${e}${details}`);
return sys.exit(1);
}
}
};
/**
* Run a specified task
*
* @param coreCompiler an instance of a minimal, bootstrap compiler for running the specified task
* @param config a configuration for the Stencil project to apply to the task run
* @param task the task to run
* @param sys the {@link d.CompilerSystem} for interacting with the operating system
* @public
* @returns a void promise
*/
export const runTask = async (
coreCompiler: CoreCompiler,
config: d.Config,
task: d.TaskCommand,
sys: d.CompilerSystem,
): Promise => {
const flags = createConfigFlags(config.flags ?? { task });
config.flags = flags;
if (!config.sys) {
config.sys = sys;
}
const strictConfig: ValidatedConfig = coreCompiler.validateConfig(config, {}).config;
switch (task) {
case 'build':
await taskBuild(coreCompiler, strictConfig);
break;
case 'docs':
await taskDocs(coreCompiler, strictConfig);
break;
case 'generate':
case 'g':
await taskGenerate(strictConfig);
break;
case 'help':
await taskHelp(strictConfig.flags, strictConfig.logger, sys);
break;
case 'prerender':
await taskPrerender(coreCompiler, strictConfig);
break;
case 'serve':
await taskServe(strictConfig);
break;
case 'telemetry':
await taskTelemetry(strictConfig.flags, sys, strictConfig.logger);
break;
case 'test':
await taskTest(strictConfig);
break;
case 'version':
console.log(coreCompiler.version);
break;
default:
strictConfig.logger.error(
`${strictConfig.logger.emoji('❌ ')}Invalid stencil command, please see the options below:`,
);
await taskHelp(strictConfig.flags, strictConfig.logger, sys);
return config.sys.exit(1);
}
};
================================================
FILE: src/cli/task-build.ts
================================================
import type * as d from '../declarations';
import { printCheckVersionResults, startCheckVersion } from './check-version';
import type { CoreCompiler } from './load-compiler';
import { startupCompilerLog } from './logs';
import { runPrerenderTask } from './task-prerender';
import { taskWatch } from './task-watch';
import { telemetryBuildFinishedAction } from './telemetry/telemetry';
export const taskBuild = async (coreCompiler: CoreCompiler, config: d.ValidatedConfig) => {
if (config.flags.watch) {
// watch build
await taskWatch(coreCompiler, config);
return;
}
// one-time build
let exitCode = 0;
try {
startupCompilerLog(coreCompiler, config);
const versionChecker = startCheckVersion(config, coreCompiler.version);
const compiler = await coreCompiler.createCompiler(config);
const results = await compiler.build();
await telemetryBuildFinishedAction(config.sys, config, coreCompiler, results);
await compiler.destroy();
if (results.hasError) {
exitCode = 1;
} else if (config.flags.prerender) {
const prerenderDiagnostics = await runPrerenderTask(
coreCompiler,
config,
results.hydrateAppFilePath,
results.componentGraph,
undefined,
);
config.logger.printDiagnostics(prerenderDiagnostics);
if (prerenderDiagnostics.some((d) => d.level === 'error')) {
exitCode = 1;
}
}
await printCheckVersionResults(versionChecker);
} catch (e) {
exitCode = 1;
config.logger.error(e);
}
if (exitCode > 0) {
return config.sys.exit(exitCode);
}
};
================================================
FILE: src/cli/task-docs.ts
================================================
import { isOutputTargetDocs } from '@utils';
import type { ValidatedConfig } from '../declarations';
import type { CoreCompiler } from './load-compiler';
import { startupCompilerLog } from './logs';
export const taskDocs = async (coreCompiler: CoreCompiler, config: ValidatedConfig) => {
config.devServer = {};
config.outputTargets = config.outputTargets.filter(isOutputTargetDocs);
config.devMode = true;
startupCompilerLog(coreCompiler, config);
const compiler = await coreCompiler.createCompiler(config);
await compiler.build();
await compiler.destroy();
};
================================================
FILE: src/cli/task-generate.ts
================================================
import { normalizePath, validateComponentTag } from '@utils';
import { join, parse, relative } from 'path';
import type { ValidatedConfig } from '../declarations';
/**
* Task to generate component boilerplate and write it to disk. This task can
* cause the program to exit with an error under various circumstances, such as
* being called in an inappropriate place, being asked to overwrite files that
* already exist, etc.
*
* @param config the user-supplied config, which we need here to access `.sys`.
* @returns a void promise
*/
export const taskGenerate = async (config: ValidatedConfig): Promise => {
if (!config.configPath) {
config.logger.error('Please run this command in your root directory (i. e. the one containing stencil.config.ts).');
return config.sys.exit(1);
}
const absoluteSrcDir = config.srcDir;
if (!absoluteSrcDir) {
config.logger.error(`Stencil's srcDir was not specified.`);
return config.sys.exit(1);
}
const { prompt } = await import('prompts');
const input =
config.flags.unknownArgs.find((arg) => !arg.startsWith('-')) ||
((await prompt({ name: 'tagName', type: 'text', message: 'Component tag name (dash-case):' })).tagName as string);
if (undefined === input) {
// in some shells (e.g. Windows PowerShell), hitting Ctrl+C results in a TypeError printed to the console.
// explicitly return here to avoid printing the error message.
return;
}
const { dir, base: componentName } = parse(input);
const tagError = validateComponentTag(componentName);
if (tagError) {
config.logger.error(tagError);
return config.sys.exit(1);
}
let cssExtension: GeneratableStylingExtension = 'css';
if (!!config.plugins.find((plugin) => plugin.name === 'sass')) {
cssExtension = await chooseSassExtension();
} else if (!!config.plugins.find((plugin) => plugin.name === 'less')) {
cssExtension = 'less';
}
const filesToGenerateExt = await chooseFilesToGenerate(cssExtension);
if (!filesToGenerateExt) {
// in some shells (e.g. Windows PowerShell), hitting Ctrl+C results in a TypeError printed to the console.
// explicitly return here to avoid printing the error message.
return;
}
const extensionsToGenerate: GeneratableExtension[] = ['tsx', ...filesToGenerateExt];
const testFolder = extensionsToGenerate.some(isTest) ? 'test' : '';
const outDir = join(absoluteSrcDir, 'components', dir, componentName);
await config.sys.createDir(normalizePath(join(outDir, testFolder)), { recursive: true });
const filesToGenerate: readonly BoilerplateFile[] = extensionsToGenerate.map((extension) => ({
extension,
path: getFilepathForFile(outDir, componentName, extension),
}));
await checkForOverwrite(filesToGenerate, config);
const writtenFiles = await Promise.all(
filesToGenerate.map((file) =>
getBoilerplateAndWriteFile(
config,
componentName,
extensionsToGenerate.includes('css') ||
extensionsToGenerate.includes('sass') ||
extensionsToGenerate.includes('scss') ||
extensionsToGenerate.includes('less'),
file,
cssExtension,
),
),
).catch((error) => config.logger.error(error));
if (!writtenFiles) {
return config.sys.exit(1);
}
// We use `console.log` here rather than our `config.logger` because we don't want
// our TUI messages to be prefixed with timestamps and so on.
//
// See STENCIL-424 for details.
console.log();
console.log(`${config.logger.gray('$')} stencil generate ${input}`);
console.log();
console.log(config.logger.bold('The following files have been generated:'));
const absoluteRootDir = config.rootDir;
writtenFiles.map((file) => console.log(` - ${relative(absoluteRootDir, file)}`));
};
/**
* Show a checkbox prompt to select the files to be generated.
*
* @param cssExtension the extension of the CSS file to be generated
* @returns a read-only array of `GeneratableExtension`, the extensions that the user has decided
* to generate
*/
const chooseFilesToGenerate = async (cssExtension: string): Promise> => {
const { prompt } = await import('prompts');
return (
await prompt({
name: 'filesToGenerate',
type: 'multiselect',
message: 'Which additional files do you want to generate?',
choices: [
{ value: cssExtension, title: `Stylesheet (.${cssExtension})`, selected: true },
{ value: 'spec.tsx', title: 'Spec Test (.spec.tsx)', selected: true },
{ value: 'e2e.ts', title: 'E2E Test (.e2e.ts)', selected: true },
],
})
).filesToGenerate;
};
const chooseSassExtension = async () => {
const { prompt } = await import('prompts');
return (
await prompt({
name: 'sassFormat',
type: 'select',
message:
'Which Sass format would you like to use? (More info: https://sass-lang.com/documentation/syntax/#the-indented-syntax)',
choices: [
{ value: 'sass', title: `*.sass Format`, selected: true },
{ value: 'scss', title: '*.scss Format' },
],
})
).sassFormat;
};
/**
* Get a filepath for a file we want to generate!
*
* The filepath for a given file depends on the path, the user-supplied
* component name, the extension, and whether we're inside of a test directory.
*
* @param filePath path to where we're going to generate the component
* @param componentName the user-supplied name for the generated component
* @param extension the file extension
* @returns the full filepath to the component (with a possible `test` directory
* added)
*/
const getFilepathForFile = (filePath: string, componentName: string, extension: GeneratableExtension): string =>
isTest(extension)
? normalizePath(join(filePath, 'test', `${componentName}.${extension}`))
: normalizePath(join(filePath, `${componentName}.${extension}`));
/**
* Get the boilerplate for a file and write it to disk
*
* @param config the current config, needed for file operations
* @param componentName the component name (user-supplied)
* @param withCss are we generating CSS?
* @param file the file we want to write
* @param styleExtension extension used for styles
* @returns a `Promise` which holds the full filepath we've written to,
* used to print out a little summary of our activity to the user.
*/
const getBoilerplateAndWriteFile = async (
config: ValidatedConfig,
componentName: string,
withCss: boolean,
file: BoilerplateFile,
styleExtension: GeneratableStylingExtension,
): Promise => {
const boilerplate = getBoilerplateByExtension(componentName, file.extension, withCss, styleExtension);
await config.sys.writeFile(normalizePath(file.path), boilerplate);
return file.path;
};
/**
* Check to see if any of the files we plan to write already exist and would
* therefore be overwritten if we proceed, because we'd like to not overwrite
* people's code!
*
* This function will check all the filepaths and if it finds any files log an
* error and exit with an error code. If it doesn't find anything it will just
* peacefully return `Promise`.
*
* @param files the files we want to check
* @param config the Config object, used here to get access to `sys.readFile`
*/
const checkForOverwrite = async (files: readonly BoilerplateFile[], config: ValidatedConfig): Promise => {
const alreadyPresent: string[] = [];
await Promise.all(
files.map(async ({ path }) => {
if ((await config.sys.readFile(path)) !== undefined) {
alreadyPresent.push(path);
}
}),
);
if (alreadyPresent.length > 0) {
config.logger.error(
'Generating code would overwrite the following files:',
...alreadyPresent.map((path) => '\t' + normalizePath(path)),
);
await config.sys.exit(1);
}
};
/**
* Check if an extension is for a test
*
* @param extension the extension we want to check
* @returns a boolean indicating whether or not its a test
*/
const isTest = (extension: GeneratableExtension): boolean => {
return extension === 'e2e.ts' || extension === 'spec.tsx';
};
/**
* Get the boilerplate for a file by its extension.
*
* @param tagName the name of the component we're generating
* @param extension the file extension we want boilerplate for (.css, tsx, etc)
* @param withCss a boolean indicating whether we're generating a CSS file
* @param styleExtension extension used for styles
* @returns a string container the file boilerplate for the supplied extension
*/
export const getBoilerplateByExtension = (
tagName: string,
extension: GeneratableExtension,
withCss: boolean,
styleExtension: GeneratableStylingExtension,
): string => {
switch (extension) {
case 'tsx':
return getComponentBoilerplate(tagName, withCss, styleExtension);
case 'css':
case 'less':
case 'sass':
case 'scss':
return getStyleUrlBoilerplate(styleExtension);
case 'spec.tsx':
return getSpecTestBoilerplate(tagName);
case 'e2e.ts':
return getE2eTestBoilerplate(tagName);
default:
throw new Error(`Unkown extension "${extension}".`);
}
};
/**
* Get the boilerplate for a file containing the definition of a component
* @param tagName the name of the tag to give the component
* @param hasStyle designates if the component has an external stylesheet or not
* @param styleExtension extension used for styles
* @returns the contents of a file that defines a component
*/
const getComponentBoilerplate = (
tagName: string,
hasStyle: boolean,
styleExtension: GeneratableStylingExtension,
): string => {
const decorator = [`{`];
decorator.push(` tag: '${tagName}',`);
if (hasStyle) {
decorator.push(` styleUrl: '${tagName}.${styleExtension}',`);
}
decorator.push(` shadow: true,`);
decorator.push(`}`);
return `import { Component, Host, h } from '@stencil/core';
@Component(${decorator.join('\n')})
export class ${toPascalCase(tagName)} {
render() {
return (
);
}
}
`;
};
/**
* Get the boilerplate for style for a generated component
* @param ext extension used for styles
* @returns a boilerplate CSS block
*/
const getStyleUrlBoilerplate = (ext: GeneratableExtension): string =>
ext === 'sass'
? `:host
display: block
`
: `:host {
display: block;
}
`;
/**
* Get the boilerplate for a file containing a spec (unit) test for a component
* @param tagName the name of the tag associated with the component under test
* @returns the contents of a file that unit tests a component
*/
const getSpecTestBoilerplate = (tagName: string): string =>
`import { newSpecPage } from '@stencil/core/testing';
import { ${toPascalCase(tagName)} } from '../${tagName}';
describe('${tagName}', () => {
it('renders', async () => {
const page = await newSpecPage({
components: [${toPascalCase(tagName)}],
html: \`<${tagName}>\`,
});
expect(page.root).toEqualHtml(\`
<${tagName}>
\`);
});
});
`;
/**
* Get the boilerplate for a file containing an end-to-end (E2E) test for a component
* @param tagName the name of the tag associated with the component under test
* @returns the contents of a file that E2E tests a component
*/
const getE2eTestBoilerplate = (tagName: string): string =>
`import { newE2EPage } from '@stencil/core/testing';
describe('${tagName}', () => {
it('renders', async () => {
const page = await newE2EPage();
await page.setContent('<${tagName}>');
const element = await page.find('${tagName}');
expect(element).toHaveClass('hydrated');
});
});
`;
/**
* Convert a dash case string to pascal case.
* @param str the string to convert
* @returns the converted input as pascal case
*/
const toPascalCase = (str: string): string =>
str.split('-').reduce((res, part) => res + part[0].toUpperCase() + part.slice(1), '');
/**
* Extensions available to generate.
*/
export type GeneratableExtension = 'tsx' | 'spec.tsx' | 'e2e.ts' | GeneratableStylingExtension;
/**
* Extensions available to generate.
*/
export type GeneratableStylingExtension = 'css' | 'sass' | 'scss' | 'less';
/**
* A little interface to wrap up the info we need to pass around for generating
* and writing boilerplate.
*/
export interface BoilerplateFile {
extension: GeneratableExtension;
/**
* The full path to the file we want to generate.
*/
path: string;
}
================================================
FILE: src/cli/task-help.ts
================================================
import type * as d from '../declarations';
import { ConfigFlags } from './config-flags';
import { taskTelemetry } from './task-telemetry';
/**
* Entrypoint for the Help task, providing Stencil usage context to the user
* @param flags configuration flags provided to Stencil when a task was call (either this task or a task that invokes
* telemetry)
* @param logger a logging implementation to log the results out to the user
* @param sys the abstraction for interfacing with the operating system
*/
export const taskHelp = async (flags: ConfigFlags, logger: d.Logger, sys: d.CompilerSystem): Promise => {
const prompt = logger.dim(sys.details?.platform === 'windows' ? '>' : '$');
console.log(`
${logger.bold('Build:')} ${logger.dim('Build components for development or production.')}
${prompt} ${logger.green('stencil build [--dev] [--watch] [--prerender] [--debug]')}
${logger.cyan('--dev')} ${logger.dim('.............')} Development build
${logger.cyan('--watch')} ${logger.dim('...........')} Rebuild when files update
${logger.cyan('--serve')} ${logger.dim('...........')} Start the dev-server
${logger.cyan('--prerender')} ${logger.dim('.......')} Prerender the application
${logger.cyan('--docs')} ${logger.dim('............')} Generate component readme.md docs
${logger.cyan('--config')} ${logger.dim('..........')} Set stencil config file
${logger.cyan('--stats')} ${logger.dim('...........')} Write stats, optional file path (default: stencil-stats.json)
${logger.cyan('--log')} ${logger.dim('.............')} Write stencil-build.log file
${logger.cyan('--debug')} ${logger.dim('...........')} Set the log level to debug
${logger.bold('Test:')} ${logger.dim('Run unit and end-to-end tests.')}
${prompt} ${logger.green('stencil test [--spec] [--e2e]')}
${logger.cyan('--spec')} ${logger.dim('............')} Run unit tests with Jest
${logger.cyan('--e2e')} ${logger.dim('.............')} Run e2e tests with Puppeteer
${logger.bold('Generate:')} ${logger.dim('Bootstrap components.')}
${prompt} ${logger.green('stencil generate')} or ${logger.green('stencil g')}
`);
await taskTelemetry(flags, sys, logger);
console.log(`
${logger.bold('Examples:')}
${prompt} ${logger.green('stencil build --dev --watch --serve')}
${prompt} ${logger.green('stencil build --prerender')}
${prompt} ${logger.green('stencil test --spec --e2e')}
${prompt} ${logger.green('stencil telemetry on')}
${prompt} ${logger.green('stencil generate')}
${prompt} ${logger.green('stencil g my-component')}
`);
};
================================================
FILE: src/cli/task-info.ts
================================================
import type { CompilerSystem, Logger } from '../declarations';
import type { CoreCompiler } from './load-compiler';
/**
* Generate the output for Stencils 'info' task, and log that output - `npx stencil info`
* @param coreCompiler the compiler instance to derive certain version information from
* @param sys the compiler system instance that provides details about the system Stencil is running on
* @param logger the logger instance to use to log information out to
*/
export const taskInfo = (coreCompiler: CoreCompiler, sys: CompilerSystem, logger: Logger): void => {
const details = sys.details;
const versions = coreCompiler.versions;
console.log(``);
console.log(`${logger.cyan(' System:')} ${sys.name} ${sys.version}`);
if (details) {
console.log(`${logger.cyan(' Platform:')} ${details.platform} (${details.release})`);
console.log(
`${logger.cyan(' CPU Model:')} ${details.cpuModel} (${sys.hardwareConcurrency} cpu${
sys.hardwareConcurrency !== 1 ? 's' : ''
})`,
);
}
console.log(`${logger.cyan(' Compiler:')} ${sys.getCompilerExecutingPath()}`);
console.log(`${logger.cyan(' Build:')} ${coreCompiler.buildId}`);
console.log(`${logger.cyan(' Stencil:')} ${coreCompiler.version}${logger.emoji(' ' + coreCompiler.vermoji)}`);
console.log(`${logger.cyan(' TypeScript:')} ${versions.typescript}`);
console.log(`${logger.cyan(' Rollup:')} ${versions.rollup}`);
console.log(`${logger.cyan(' Parse5:')} ${versions.parse5}`);
console.log(`${logger.cyan(' jQuery:')} ${versions.jquery}`);
console.log(`${logger.cyan(' Terser:')} ${versions.terser}`);
console.log(``);
};
================================================
FILE: src/cli/task-prerender.ts
================================================
import { catchError } from '@utils';
import type { BuildResultsComponentGraph, Diagnostic, ValidatedConfig } from '../declarations';
import type { CoreCompiler } from './load-compiler';
import { startupCompilerLog } from './logs';
export const taskPrerender = async (coreCompiler: CoreCompiler, config: ValidatedConfig) => {
startupCompilerLog(coreCompiler, config);
const hydrateAppFilePath = config.flags.unknownArgs[0];
if (typeof hydrateAppFilePath !== 'string') {
config.logger.error(`Missing hydrate app script path`);
return config.sys.exit(1);
}
const srcIndexHtmlPath = config.srcIndexHtml;
const diagnostics = await runPrerenderTask(coreCompiler, config, hydrateAppFilePath, undefined, srcIndexHtmlPath);
config.logger.printDiagnostics(diagnostics);
if (diagnostics.some((d) => d.level === 'error')) {
return config.sys.exit(1);
}
};
export const runPrerenderTask = async (
coreCompiler: CoreCompiler,
config: ValidatedConfig,
hydrateAppFilePath?: string,
componentGraph?: BuildResultsComponentGraph,
srcIndexHtmlPath?: string,
) => {
const diagnostics: Diagnostic[] = [];
try {
const prerenderer = await coreCompiler.createPrerenderer(config);
const results = await prerenderer.start({
hydrateAppFilePath,
componentGraph,
srcIndexHtmlPath,
});
diagnostics.push(...results.diagnostics);
} catch (e: any) {
catchError(diagnostics, e);
}
return diagnostics;
};
================================================
FILE: src/cli/task-serve.ts
================================================
import { isString } from '@utils';
import type { ValidatedConfig } from '../declarations';
export const taskServe = async (config: ValidatedConfig) => {
config.suppressLogs = true;
config.flags.serve = true;
config.devServer.openBrowser = !!config.flags.open;
config.devServer.reloadStrategy = null;
config.devServer.initialLoadUrl = '/';
config.devServer.websocket = false;
config.maxConcurrentWorkers = 1;
config.devServer.root = isString(config.flags.root) ? config.flags.root : config.sys.getCurrentDirectory();
if (!config.sys.getDevServerExecutingPath || !config.sys.dynamicImport || !config.sys.onProcessInterrupt) {
throw new Error(
`Environment doesn't provide required functions: getDevServerExecutingPath, dynamicImport, onProcessInterrupt`,
);
}
const devServerPath = config.sys.getDevServerExecutingPath();
const { start }: typeof import('@stencil/core/dev-server') = await config.sys.dynamicImport(devServerPath);
const devServer = await start(config.devServer, config.logger);
console.log(`${config.logger.cyan(' Root:')} ${devServer.root}`);
console.log(`${config.logger.cyan(' Address:')} ${devServer.address}`);
console.log(`${config.logger.cyan(' Port:')} ${devServer.port}`);
console.log(`${config.logger.cyan(' Server:')} ${devServer.browserUrl}`);
console.log(``);
config.sys.onProcessInterrupt(() => {
if (devServer) {
config.logger.debug(`dev server close: ${devServer.browserUrl}`);
devServer.close();
}
});
};
================================================
FILE: src/cli/task-telemetry.ts
================================================
import type * as d from '../declarations';
import { ConfigFlags } from './config-flags';
import { checkTelemetry, disableTelemetry, enableTelemetry } from './telemetry/telemetry';
/**
* Entrypoint for the Telemetry task
* @param flags configuration flags provided to Stencil when a task was called (either this task or a task that invokes
* telemetry)
* @param sys the abstraction for interfacing with the operating system
* @param logger a logging implementation to log the results out to the user
*/
export const taskTelemetry = async (flags: ConfigFlags, sys: d.CompilerSystem, logger: d.Logger): Promise => {
const prompt = logger.dim(sys.details?.platform === 'windows' ? '>' : '$');
const isEnabling = flags.args.includes('on');
const isDisabling = flags.args.includes('off');
const INFORMATION = `Opt in or out of telemetry. Information about the data we collect is available on our website: ${logger.bold(
'https://stenciljs.com/telemetry',
)}`;
const THANK_YOU = `Thank you for helping to make Stencil better! 💖`;
const ENABLED_MESSAGE = `${logger.green('Enabled')}. ${THANK_YOU}\n\n`;
const DISABLED_MESSAGE = `${logger.red('Disabled')}\n\n`;
const hasTelemetry = await checkTelemetry(sys);
if (isEnabling) {
const result = await enableTelemetry(sys);
result
? console.log(`\n ${logger.bold('Telemetry is now ') + ENABLED_MESSAGE}`)
: console.log(`Something went wrong when enabling Telemetry.`);
return;
}
if (isDisabling) {
const result = await disableTelemetry(sys);
result
? console.log(`\n ${logger.bold('Telemetry is now ') + DISABLED_MESSAGE}`)
: console.log(`Something went wrong when disabling Telemetry.`);
return;
}
console.log(` ${logger.bold('Telemetry:')} ${logger.dim(INFORMATION)}`);
console.log(`\n ${logger.bold('Status')}: ${hasTelemetry ? ENABLED_MESSAGE : DISABLED_MESSAGE}`);
console.log(` ${prompt} ${logger.green('stencil telemetry [off|on]')}
${logger.cyan('off')} ${logger.dim('.............')} Disable sharing anonymous usage data
${logger.cyan('on')} ${logger.dim('..............')} Enable sharing anonymous usage data
`);
};
================================================
FILE: src/cli/task-test.ts
================================================
import type { TestingRunOptions, ValidatedConfig } from '../declarations';
/**
* Entrypoint for any Stencil tests
* @param config a validated Stencil configuration entity
* @returns a void promise
*/
export const taskTest = async (config: ValidatedConfig): Promise => {
config.logger.warn(
config.logger.yellow(
`[DEPRECATION] Stencil's integrated testing (the 'test' task, --spec and --e2e flags) is deprecated and will be removed in Stencil v5. ` +
`Migrate spec tests to @stencil/vitest (https://github.com/stenciljs/vitest) and ` +
`e2e / browser tests to either @stencil/vitest (https://github.com/stenciljs/vitest) or ` +
`@stencil/playwright (https://github.com/stenciljs/playwright). ` +
`See https://github.com/stenciljs/core/issues/6584 for full details.`,
),
);
config.buildDocs = false;
const testingRunOpts: TestingRunOptions = {
e2e: !!config.flags.e2e,
screenshot: !!config.flags.screenshot,
spec: !!config.flags.spec,
updateScreenshot: !!config.flags.updateScreenshot,
};
// always ensure we have jest modules installed
const ensureModuleIds = ['@types/jest', 'jest', 'jest-cli'];
if (testingRunOpts.e2e) {
// if it's an e2e test, also make sure we're got
// puppeteer modules installed and if browserExecutablePath is provided don't download Chromium use only puppeteer-core instead
const puppeteer = config.testing.browserExecutablePath ? 'puppeteer-core' : 'puppeteer';
ensureModuleIds.push(puppeteer);
if (testingRunOpts.screenshot) {
// ensure we've got pixelmatch for screenshots
config.logger.warn(
config.logger.yellow(
`EXPERIMENTAL: screenshot visual diff testing is currently under heavy development and has not reached a stable status. However, any assistance testing would be appreciated.`,
),
);
}
}
// ensure we've got the required modules installed
const diagnostics = await config.sys.lazyRequire?.ensure(config.rootDir, ensureModuleIds);
if (diagnostics && diagnostics.length > 0) {
config.logger.printDiagnostics(diagnostics);
return config.sys.exit(1);
}
try {
/**
* We dynamically import the testing submodule here in order for Stencil's lazy module checking to work properly.
*
* Prior to this call, we create a collection of string-based node module names and ensure that they're installed &
* on disk. The testing submodule includes `jest` (amongst other) testing libraries in its dependency chain. We need
* to run the lazy module check _before_ we include `jest` et al. in our dependency chain otherwise, the lazy module
* checking would fail to run properly (because we'd import `jest`, which wouldn't exist, before we even checked if
* it was installed).
*/
const { createTesting } = await import('@stencil/core/testing');
const testing = await createTesting(config);
const passed = await testing.run(testingRunOpts);
await testing.destroy();
if (!passed) {
return config.sys.exit(1);
}
} catch (e) {
config.logger.error(e);
return config.sys.exit(1);
}
};
================================================
FILE: src/cli/task-watch.ts
================================================
import type { DevServer, ValidatedConfig } from '../declarations';
import { printCheckVersionResults, startCheckVersion } from './check-version';
import type { CoreCompiler } from './load-compiler';
import { startupCompilerLog } from './logs';
export const taskWatch = async (coreCompiler: CoreCompiler, config: ValidatedConfig) => {
let devServer: DevServer | null = null;
let exitCode = 0;
try {
startupCompilerLog(coreCompiler, config);
const versionChecker = startCheckVersion(config, coreCompiler.version);
const compiler = await coreCompiler.createCompiler(config);
const watcher = await compiler.createWatcher();
if (!config.sys.getDevServerExecutingPath || !config.sys.dynamicImport || !config.sys.onProcessInterrupt) {
throw new Error(
`Environment doesn't provide required functions: getDevServerExecutingPath, dynamicImport, onProcessInterrupt`,
);
}
if (config.flags.serve) {
const devServerPath = config.sys.getDevServerExecutingPath();
const { start }: typeof import('@stencil/core/dev-server') = await config.sys.dynamicImport(devServerPath);
devServer = await start(config.devServer, config.logger, watcher);
}
config.sys.onProcessInterrupt(() => {
config.logger.debug(`close watch`);
compiler && compiler.destroy();
});
const rmVersionCheckerLog = watcher.on('buildFinish', async () => {
// log the version check one time
rmVersionCheckerLog();
printCheckVersionResults(versionChecker);
});
if (devServer) {
const rmDevServerLog = watcher.on('buildFinish', () => {
// log the dev server url one time
rmDevServerLog();
const url = devServer?.browserUrl ?? 'UNKNOWN URL';
config.logger.info(`${config.logger.cyan(url)}\n`);
});
}
const closeResults = await watcher.start();
if (closeResults.exitCode > 0) {
exitCode = closeResults.exitCode;
}
} catch (e) {
exitCode = 1;
config.logger.error(e);
}
if (devServer) {
await devServer.close();
}
if (exitCode > 0) {
return config.sys.exit(exitCode);
}
};
================================================
FILE: src/cli/telemetry/helpers.ts
================================================
import type * as d from '../../declarations';
import { ConfigFlags } from '../config-flags';
export const tryFn = async Promise, R>(fn: T, ...args: any[]): Promise => {
try {
return await fn(...args);
} catch {
// ignore
}
return null;
};
export const isInteractive = (sys: d.CompilerSystem, flags: ConfigFlags, object?: d.TerminalInfo): boolean => {
const terminalInfo =
object ||
Object.freeze({
tty: sys.isTTY() ? true : false,
ci:
['CI', 'BUILD_ID', 'BUILD_NUMBER', 'BITBUCKET_COMMIT', 'CODEBUILD_BUILD_ARN'].filter(
(v) => !!sys.getEnvironmentVar?.(v),
).length > 0 || !!flags.ci,
});
return terminalInfo.tty && !terminalInfo.ci;
};
export const UUID_REGEX = new RegExp(/^[0-9A-F]{8}-[0-9A-F]{4}-4[0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}$/i);
// Plucked from https://github.com/ionic-team/capacitor/blob/b893a57aaaf3a16e13db9c33037a12f1a5ac92e0/cli/src/util/uuid.ts
export function uuidv4(): string {
return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
const r = (Math.random() * 16) | 0;
const v = c == 'x' ? r : (r & 0x3) | 0x8;
return v.toString(16);
});
}
/**
* Reads and parses a JSON file from the given `path`
* @param sys The system where the command is invoked
* @param path the path on the file system to read and parse
* @returns the parsed JSON
*/
export async function readJson(sys: d.CompilerSystem, path: string): Promise {
const file = await sys.readFile(path);
return !!file && JSON.parse(file);
}
/**
* Does the command have the debug flag?
* @param flags The configuration flags passed into the Stencil command
* @returns true if --debug has been passed, otherwise false
*/
export function hasDebug(flags: ConfigFlags): boolean {
return !!flags.debug;
}
/**
* Does the command have the verbose and debug flags?
* @param flags The configuration flags passed into the Stencil command
* @returns true if both --debug and --verbose have been passed, otherwise false
*/
export function hasVerbose(flags: ConfigFlags): boolean {
return !!flags.verbose && hasDebug(flags);
}
================================================
FILE: src/cli/telemetry/shouldTrack.ts
================================================
import * as d from '../../declarations';
import { isInteractive } from './helpers';
import { checkTelemetry } from './telemetry';
/**
* Used to determine if tracking should occur.
* @param config The config passed into the Stencil command
* @param sys The system where the command is invoked
* @param ci whether or not the process is running in a Continuous Integration (CI) environment
* @returns true if telemetry should be sent, false otherwise
*/
export async function shouldTrack(config: d.ValidatedConfig, sys: d.CompilerSystem, ci?: boolean) {
return !ci && isInteractive(sys, config.flags) && (await checkTelemetry(sys));
}
================================================
FILE: src/cli/telemetry/telemetry.ts
================================================
import { isOutputTargetHydrate, WWW } from '@utils';
import type * as d from '../../declarations';
import { readConfig, updateConfig, writeConfig } from '../ionic-config';
import { CoreCompiler } from '../load-compiler';
import { hasDebug, hasVerbose, readJson, tryFn, uuidv4 } from './helpers';
import { shouldTrack } from './shouldTrack';
/**
* Used to within taskBuild to provide the component_count property.
*
* @param sys The system where the command is invoked
* @param config The config passed into the Stencil command
* @param coreCompiler The compiler used to do builds
* @param result The results of a compiler build.
*/
export async function telemetryBuildFinishedAction(
sys: d.CompilerSystem,
config: d.ValidatedConfig,
coreCompiler: CoreCompiler,
result: d.CompilerBuildResults,
) {
const tracking = await shouldTrack(config, sys, !!config.flags.ci);
if (!tracking) {
return;
}
const component_count = result.componentGraph ? Object.keys(result.componentGraph).length : undefined;
const data = await prepareData(coreCompiler, config, sys, result.duration, component_count);
await sendMetric(sys, config, 'stencil_cli_command', data);
config.logger.debug(`${config.logger.blue('Telemetry')}: ${config.logger.gray(JSON.stringify(data))}`);
}
/**
* A function to wrap a compiler task function around. Will send telemetry if, and only if, the machine allows.
*
* @param sys The system where the command is invoked
* @param config The config passed into the Stencil command
* @param coreCompiler The compiler used to do builds
* @param action A Promise-based function to call in order to get the duration of any given command.
* @returns void
*/
export async function telemetryAction(
sys: d.CompilerSystem,
config: d.ValidatedConfig,
coreCompiler: CoreCompiler,
action?: d.TelemetryCallback,
) {
const tracking = await shouldTrack(config, sys, !!config.flags.ci);
let duration = undefined;
let error: any;
if (action) {
const start = new Date();
try {
await action();
} catch (e) {
error = e;
}
const end = new Date();
duration = end.getTime() - start.getTime();
}
// We'll get componentCount details inside the taskBuild, so let's not send two messages.
if (!tracking || (config.flags.task == 'build' && !config.flags.args.includes('--watch'))) {
return;
}
const data = await prepareData(coreCompiler, config, sys, duration);
await sendMetric(sys, config, 'stencil_cli_command', data);
config.logger.debug(`${config.logger.blue('Telemetry')}: ${config.logger.gray(JSON.stringify(data))}`);
if (error) {
throw error;
}
}
/**
* Helper function to determine if a Stencil configuration builds an application.
*
* This function is a rough approximation whether an application is generated as a part of a Stencil build, based on
* contents of the project's `stencil.config.ts` file.
*
* @param config the configuration used by the Stencil project
* @returns true if we believe the project generates an application, false otherwise
*/
export function hasAppTarget(config: d.ValidatedConfig): boolean {
return config.outputTargets.some(
(target) => target.type === WWW && (!!target.serviceWorker || (!!target.baseUrl && target.baseUrl !== '/')),
);
}
export function isUsingYarn(sys: d.CompilerSystem) {
return sys.getEnvironmentVar?.('npm_execpath')?.includes('yarn') || false;
}
/**
* Build a list of the different types of output targets used in a Stencil configuration.
*
* Duplicate entries will not be returned from the list
*
* @param config the configuration used by the Stencil project
* @returns a unique list of output target types found in the Stencil configuration
*/
export function getActiveTargets(config: d.ValidatedConfig): string[] {
const result = config.outputTargets.map((t) => t.type);
return Array.from(new Set(result));
}
/**
* Prepare data for telemetry
*
* @param coreCompiler the core compiler
* @param config the current Stencil config
* @param sys the compiler system instance in use
* @param duration_ms the duration of the action being tracked
* @param component_count the number of components being built (optional)
* @returns a Promise wrapping data for the telemetry endpoint
*/
export const prepareData = async (
coreCompiler: CoreCompiler,
config: d.ValidatedConfig,
sys: d.CompilerSystem,
duration_ms: number | undefined,
component_count: number | undefined = undefined,
): Promise => {
const { typescript, rollup } = coreCompiler.versions || { typescript: 'unknown', rollup: 'unknown' };
const { packages, packagesNoVersions } = await getInstalledPackages(sys, config);
const targets = getActiveTargets(config);
const yarn = isUsingYarn(sys);
const stencil = coreCompiler.version || 'unknown';
const system = `${sys.name} ${sys.version}`;
const os_name = sys.details?.platform;
const os_version = sys.details?.release;
const cpu_model = sys.details?.cpuModel;
const build = coreCompiler.buildId || 'unknown';
const has_app_pwa_config = hasAppTarget(config);
const anonymizedConfig = anonymizeConfigForTelemetry(config);
return {
arguments: config.flags.args,
build,
component_count,
config: anonymizedConfig,
cpu_model,
duration_ms,
has_app_pwa_config,
os_name,
os_version,
packages,
packages_no_versions: packagesNoVersions,
rollup,
stencil,
system,
system_major: getMajorVersion(system),
targets,
task: config.flags.task,
typescript,
yarn,
};
};
// Setting a key type to `never` excludes it from a mapped type, so we
// can get only keys which map to a string value by excluding all keys `K`
// where `d.Config[K]` does not extend `string`.
type ConfigStringKeys = keyof {
[K in keyof d.Config as Required[K] extends string ? K : never]: d.Config[K];
};
// props in output targets for which we retain their original values when
// preparing a config for telemetry
//
// we omit the values of all other fields on output targets.
const OUTPUT_TARGET_KEYS_TO_KEEP: ReadonlyArray = ['type'];
// top-level config props that we anonymize for telemetry
const CONFIG_PROPS_TO_ANONYMIZE: ReadonlyArray = [
'rootDir',
'fsNamespace',
'packageJsonFilePath',
'namespace',
'srcDir',
'srcIndexHtml',
'buildLogFilePath',
'cacheDir',
'configPath',
'tsconfig',
];
// Props we delete entirely from the config for telemetry
//
// TODO(STENCIL-469): Investigate improving anonymization for tsCompilerOptions and devServer
const CONFIG_PROPS_TO_DELETE: ReadonlyArray = [
'commonjs',
'devServer',
'env',
'logger',
'rollupConfig',
'sys',
'testing',
'tsCompilerOptions',
];
/**
* Anonymize the config for telemetry, replacing potentially revealing config props
* with a placeholder string if they are present (this lets us still track how frequently
* these config options are being used)
*
* @param config the config to anonymize
* @returns an anonymized copy of the same config
*/
export const anonymizeConfigForTelemetry = (config: d.ValidatedConfig): d.Config => {
const anonymizedConfig: d.Config = { ...config };
for (const prop of CONFIG_PROPS_TO_ANONYMIZE) {
if (anonymizedConfig[prop] !== undefined) {
anonymizedConfig[prop] = 'omitted';
}
}
anonymizedConfig.outputTargets = config.outputTargets.map((target) => {
// Anonymize the outputTargets on our configuration, taking advantage of the
// optional 2nd argument to `JSON.stringify`. If anything is not a string
// we retain it so that any nested properties are handled, else we check
// whether it's in our 'keep' list to decide whether to keep it or replace it
// with `"omitted"`.
const anonymizedOT = JSON.parse(
JSON.stringify(target, (key, value) => {
if (!(typeof value === 'string')) {
return value;
}
if (OUTPUT_TARGET_KEYS_TO_KEEP.includes(key)) {
return value;
}
return 'omitted';
}),
);
// this prop has to be handled separately because it is an array
// so the replace function above will be called with all of its
// members, giving us `["omitted", "omitted", ...]`.
//
// Instead, we check for its presence and manually copy over.
if (isOutputTargetHydrate(target) && target.external) {
anonymizedOT['external'] = target.external.concat();
}
return anonymizedOT;
});
// TODO(STENCIL-469): Investigate improving anonymization for tsCompilerOptions and devServer
for (const prop of CONFIG_PROPS_TO_DELETE) {
delete anonymizedConfig[prop];
}
return anonymizedConfig;
};
/**
* Reads package-lock.json, yarn.lock, and package.json files in order to cross-reference
* the dependencies and devDependencies properties. Pulls up the current installed version
* of each package under the @stencil, @ionic, and @capacitor scopes.
*
* @param sys the system instance where telemetry is invoked
* @param config the Stencil configuration associated with the current task that triggered telemetry
* @returns an object listing all dev and production dependencies under the aforementioned scopes
*/
async function getInstalledPackages(
sys: d.CompilerSystem,
config: d.ValidatedConfig,
): Promise<{ packages: string[]; packagesNoVersions: string[] }> {
let packages: string[] = [];
let packagesNoVersions: string[] = [];
const yarn = isUsingYarn(sys);
try {
// Read package.json and package-lock.json
const appRootDir = sys.getCurrentDirectory();
const packageJson: d.PackageJsonData | null = await tryFn(
readJson,
sys,
sys.resolvePath(appRootDir + '/package.json'),
);
// They don't have a package.json for some reason? Eject button.
if (!packageJson) {
return { packages, packagesNoVersions };
}
const rawPackages: [string, string][] = Object.entries({
...packageJson.devDependencies,
...packageJson.dependencies,
});
// Collect packages only in the stencil, ionic, or capacitor org's:
// https://www.npmjs.com/org/stencil
const ionicPackages = rawPackages.filter(
([k]) => k.startsWith('@stencil/') || k.startsWith('@ionic/') || k.startsWith('@capacitor/'),
);
try {
packages = yarn ? await yarnPackages(sys, ionicPackages) : await npmPackages(sys, ionicPackages);
} catch (e) {
packages = ionicPackages.map(([k, v]) => `${k}@${v.replace('^', '')}`);
}
packagesNoVersions = ionicPackages.map(([k]) => `${k}`);
return { packages, packagesNoVersions };
} catch (err) {
hasDebug(config.flags) && console.error(err);
return { packages, packagesNoVersions };
}
}
/**
* Visits the npm lock file to find the exact versions that are installed
* @param sys The system where the command is invoked
* @param ionicPackages a list of the found packages matching `@stencil`, `@capacitor`, or `@ionic` from the package.json file.
* @returns an array of strings of all the packages and their versions.
*/
async function npmPackages(sys: d.CompilerSystem, ionicPackages: [string, string][]): Promise {
const appRootDir = sys.getCurrentDirectory();
const packageLockJson: any = await tryFn(readJson, sys, sys.resolvePath(appRootDir + '/package-lock.json'));
return ionicPackages.map(([k, v]) => {
let version = packageLockJson?.dependencies[k]?.version ?? packageLockJson?.devDependencies[k]?.version ?? v;
version = version.includes('file:') ? sanitizeDeclaredVersion(v) : version;
return `${k}@${version}`;
});
}
/**
* Visits the yarn lock file to find the exact versions that are installed
* @param sys The system where the command is invoked
* @param ionicPackages a list of the found packages matching `@stencil`, `@capacitor`, or `@ionic` from the package.json file.
* @returns an array of strings of all the packages and their versions.
*/
async function yarnPackages(sys: d.CompilerSystem, ionicPackages: [string, string][]): Promise {
const appRootDir = sys.getCurrentDirectory();
const yarnLock = sys.readFileSync(sys.resolvePath(appRootDir + '/yarn.lock'));
const yarnLockYml = sys.parseYarnLockFile?.(yarnLock);
return ionicPackages.map(([k, v]) => {
const identifiedVersion = `${k}@${v}`;
let version = yarnLockYml?.object[identifiedVersion]?.version;
version = version && version.includes('undefined') ? sanitizeDeclaredVersion(identifiedVersion) : version;
return `${k}@${version}`;
});
}
/**
* This function is used for fallback purposes, where an npm or yarn lock file doesn't exist in the consumers directory.
* This will strip away '*', '^' and '~' from the declared package versions in a package.json.
* @param version the raw semver pattern identifier version string
* @returns a cleaned up representation without any qualifiers
*/
function sanitizeDeclaredVersion(version: string): string {
return version.replace(/[*^~]/g, '');
}
/**
* If telemetry is enabled, send a metric to an external data store
*
* @param sys the system instance where telemetry is invoked
* @param config the Stencil configuration associated with the current task that triggered telemetry
* @param name the name of a trackable metric. Note this name is not necessarily a scalar value to track, like
* "Stencil Version". For example, "stencil_cli_command" is a name that is used to track all CLI command information.
* @param value the data to send to the external data store under the provided name argument
*/
export async function sendMetric(
sys: d.CompilerSystem,
config: d.ValidatedConfig,
name: string,
value: d.TrackableData,
): Promise {
const session_id = await getTelemetryToken(sys);
const message: d.Metric = {
name,
timestamp: new Date().toISOString(),
source: 'stencil_cli',
value,
session_id,
};
await sendTelemetry(sys, config, message);
}
/**
* Used to read the config file's tokens.telemetry property.
*
* @param sys The system where the command is invoked
* @returns string
*/
async function getTelemetryToken(sys: d.CompilerSystem) {
const config = await readConfig(sys);
if (config['tokens.telemetry'] === undefined) {
config['tokens.telemetry'] = uuidv4();
await writeConfig(sys, config);
}
return config['tokens.telemetry'];
}
/**
* Issues a request to the telemetry server.
* @param sys The system where the command is invoked
* @param config The config passed into the Stencil command
* @param data Data to be tracked
*/
async function sendTelemetry(sys: d.CompilerSystem, config: d.ValidatedConfig, data: d.Metric): Promise {
try {
const now = new Date().toISOString();
const body = {
metrics: [data],
sent_at: now,
};
if (!sys.fetch) {
throw new Error('No fetch implementation available');
}
// This request is only made if telemetry is on.
const response = await sys.fetch('https://api.ionicjs.com/events/metrics', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
});
hasVerbose(config.flags) &&
console.debug('\nSent %O metric to events service (status: %O)', data.name, response.status, '\n');
if (response.status !== 204) {
hasVerbose(config.flags) &&
console.debug('\nBad response from events service. Request body: %O', response.body.toString(), '\n');
}
} catch (e) {
hasVerbose(config.flags) && console.debug('Telemetry request failed:', e);
}
}
/**
* Checks if telemetry is enabled on this machine
* @param sys The system where the command is invoked
* @returns true if telemetry is enabled, false otherwise
*/
export async function checkTelemetry(sys: d.CompilerSystem): Promise {
const config = await readConfig(sys);
if (config['telemetry.stencil'] === undefined) {
config['telemetry.stencil'] = true;
await writeConfig(sys, config);
}
return config['telemetry.stencil'];
}
/**
* Writes to the config file, enabling telemetry for this machine.
* @param sys The system where the command is invoked
* @returns true if writing the file was successful, false otherwise
*/
export async function enableTelemetry(sys: d.CompilerSystem): Promise {
return await updateConfig(sys, { 'telemetry.stencil': true });
}
/**
* Writes to the config file, disabling telemetry for this machine.
* @param sys The system where the command is invoked
* @returns true if writing the file was successful, false otherwise
*/
export async function disableTelemetry(sys: d.CompilerSystem): Promise {
return await updateConfig(sys, { 'telemetry.stencil': false });
}
/**
* Takes in a semver string in order to return the major version.
* @param version The fully qualified semver version
* @returns a string of the major version
*/
function getMajorVersion(version: string): string {
const parts = version.split('.');
return parts[0];
}
================================================
FILE: src/cli/telemetry/test/helpers.spec.ts
================================================
import { createSystem } from '../../../compiler/sys/stencil-sys';
import { ConfigFlags, createConfigFlags } from '../../config-flags';
import { hasDebug, hasVerbose, isInteractive, tryFn, uuidv4 } from '../helpers';
describe('hasDebug', () => {
it('returns true when the "debug" flag is true', () => {
const flags = createConfigFlags({
debug: true,
});
expect(hasDebug(flags)).toBe(true);
});
it('returns false when the "debug" flag is false', () => {
const flags = createConfigFlags({
debug: false,
});
expect(hasDebug(flags)).toBe(false);
});
it('returns false when a flag is not passed', () => {
const flags = createConfigFlags({});
expect(hasDebug(flags)).toBe(false);
});
});
describe('hasVerbose', () => {
it.each>([
{ debug: true, verbose: false },
{ debug: false, verbose: true },
{ debug: false, verbose: false },
])('returns false when debug=$debug and verbose=$verbose', (flagOverrides) => {
const flags = createConfigFlags(flagOverrides);
expect(hasVerbose(flags)).toBe(false);
});
it('returns true when debug=true and verbose=true', () => {
const flags = createConfigFlags({
debug: true,
verbose: true,
});
expect(hasVerbose(flags)).toBe(true);
});
});
describe('uuidv4', () => {
it('outputs a UUID', () => {
const pattern = new RegExp(/^[0-9A-F]{8}-[0-9A-F]{4}-4[0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}$/i);
const uuid = uuidv4();
expect(!!uuid.match(pattern)).toBe(true);
});
});
describe('isInteractive', () => {
const sys = createSystem();
it('returns false by default', () => {
const result = isInteractive(sys, createConfigFlags({ ci: false }), { ci: false, tty: false });
expect(result).toBe(false);
});
it('returns false when tty is false', () => {
const result = isInteractive(sys, createConfigFlags({ ci: true }), { ci: true, tty: false });
expect(result).toBe(false);
});
it('returns false when ci is true', () => {
const result = isInteractive(sys, createConfigFlags({ ci: true }), { ci: true, tty: true });
expect(result).toBe(false);
});
it('returns true when tty is true and ci is false', () => {
const result = isInteractive(sys, createConfigFlags({ ci: false }), { ci: false, tty: true });
expect(result).toBe(true);
});
});
describe('tryFn', () => {
it('handles failures correctly', async () => {
const result = await tryFn(async () => {
throw new Error('Uh oh!');
});
expect(result).toBe(null);
});
it('handles success correctly', async () => {
const result = await tryFn(async () => {
return true;
});
expect(result).toBe(true);
});
it('handles returning false correctly', async () => {
const result = await tryFn(async () => {
return false;
});
expect(result).toBe(false);
});
});
================================================
FILE: src/cli/telemetry/test/telemetry.spec.ts
================================================
import * as coreCompiler from '@stencil/core/compiler';
import { mockValidatedConfig } from '@stencil/core/testing';
import { DIST, DIST_CUSTOM_ELEMENTS, DIST_HYDRATE_SCRIPT, WWW } from '@utils';
import { createConfigFlags } from '../../../cli/config-flags';
import { createSystem } from '../../../compiler/sys/stencil-sys';
import type * as d from '../../../declarations';
import * as shouldTrack from '../shouldTrack';
import * as telemetry from '../telemetry';
import { anonymizeConfigForTelemetry } from '../telemetry';
describe('telemetryBuildFinishedAction', () => {
let config: d.ValidatedConfig;
let sys: d.CompilerSystem;
beforeEach(() => {
sys = createSystem();
config = mockValidatedConfig({
flags: createConfigFlags({ task: 'build' }),
outputTargets: [],
sys,
});
});
it('issues a network request when complete', async () => {
const spyShouldTrack = jest.spyOn(shouldTrack, 'shouldTrack');
spyShouldTrack.mockReturnValue(
new Promise((resolve) => {
resolve(true);
}),
);
const results = {
componentGraph: {},
duration: 100,
} as d.CompilerBuildResults;
await telemetry.telemetryBuildFinishedAction(sys, config, coreCompiler, results);
expect(spyShouldTrack).toHaveBeenCalled();
spyShouldTrack.mockRestore();
});
});
describe('telemetryAction', () => {
let config: d.ValidatedConfig;
let sys: d.CompilerSystem;
beforeEach(() => {
sys = createSystem();
config = mockValidatedConfig({
flags: createConfigFlags({ task: 'build' }),
outputTargets: [],
sys,
});
});
it('issues a network request when no async function is passed', async () => {
const spyShouldTrack = jest.spyOn(shouldTrack, 'shouldTrack');
spyShouldTrack.mockReturnValue(
new Promise((resolve) => {
resolve(true);
}),
);
await telemetry.telemetryAction(sys, config, coreCompiler, () => {});
expect(spyShouldTrack).toHaveBeenCalled();
spyShouldTrack.mockRestore();
});
it('issues a network request when passed async function is complete', async () => {
const spyShouldTrack = jest.spyOn(shouldTrack, 'shouldTrack');
spyShouldTrack.mockReturnValue(
new Promise((resolve) => {
resolve(true);
}),
);
await telemetry.telemetryAction(sys, config, coreCompiler, async () => {
new Promise((resolve) => {
setTimeout(() => {
resolve(true);
}, 1000);
});
});
expect(spyShouldTrack).toHaveBeenCalled();
spyShouldTrack.mockRestore();
});
});
describe('checkTelemetry', () => {
const sys = createSystem();
it('will read and write from a file, returning the correct status', async () => {
await telemetry.enableTelemetry(sys);
expect(await telemetry.checkTelemetry(sys)).toBe(true);
await telemetry.disableTelemetry(sys);
expect(await telemetry.checkTelemetry(sys)).toBe(false);
await telemetry.enableTelemetry(sys);
expect(await telemetry.checkTelemetry(sys)).toBe(true);
});
});
describe('hasAppTarget()', () => {
let config: d.ValidatedConfig;
let sys: d.CompilerSystem;
beforeEach(() => {
sys = createSystem();
config = mockValidatedConfig({ sys });
});
it("returns 'false' when `outputTargets` is empty", () => {
config.outputTargets = [];
expect(telemetry.hasAppTarget(config)).toBe(false);
});
it("returns 'false' when `outputTargets` contains `www` with no `baseUrl` and no service worker", () => {
config.outputTargets = [{ type: WWW }];
expect(telemetry.hasAppTarget(config)).toBe(false);
});
it("returns 'false' when `outputTargets` contains `www` with '/' baseUrl value", () => {
config.outputTargets = [{ type: WWW, baseUrl: '/' }];
expect(telemetry.hasAppTarget(config)).toBe(false);
});
it("returns 'true' when `outputTargets` contains `www` with a service worker", () => {
config.outputTargets = [{ type: WWW, serviceWorker: { swDest: './tmp' } }];
expect(telemetry.hasAppTarget(config)).toBe(true);
});
it("returns 'true' when `outputTargets` contains `www` with baseUrl", () => {
config.outputTargets = [{ type: WWW, baseUrl: 'https://example.com' }];
expect(telemetry.hasAppTarget(config)).toBe(true);
});
it("returns 'true' when `outputTargets` contains `www` with serviceWorker and baseUrl", () => {
config.outputTargets = [{ type: WWW, baseUrl: 'https://example.com', serviceWorker: { swDest: './tmp' } }];
expect(telemetry.hasAppTarget(config)).toBe(true);
});
});
describe('prepareData', () => {
let config: d.ValidatedConfig;
let sys: d.CompilerSystem;
beforeEach(() => {
config = mockValidatedConfig();
sys = config.sys;
// set static name + versions, otherwise tests will pull in the dev build's data (which changes per build)
sys.name = 'in-memory';
sys.version = '__VERSION:STENCIL__';
});
it('prepares an object to send to ionic', async () => {
const data = await telemetry.prepareData(coreCompiler, config, sys, 1000);
expect(data).toEqual({
arguments: [],
build: coreCompiler.buildId,
component_count: undefined,
// the configuration generation is tested elsewhere, just verify we're sending something under this flag
config: expect.any(Object),
cpu_model: '',
duration_ms: 1000,
has_app_pwa_config: false,
os_name: '',
os_version: '',
packages: [],
packages_no_versions: [],
rollup: coreCompiler.versions.rollup,
stencil: coreCompiler.versions.stencil,
system: 'in-memory __VERSION:STENCIL__',
system_major: 'in-memory __VERSION:STENCIL__',
targets: [],
task: null,
typescript: coreCompiler.versions.typescript,
yarn: false,
});
});
describe('has_app_pwa_config property', () => {
it('sets `has_app_pwa_config` to true when there is a service worker', async () => {
const config = mockValidatedConfig({
outputTargets: [{ type: 'www', baseUrl: 'https://example.com' }],
});
const data = await telemetry.prepareData(coreCompiler, config, sys, 1000);
expect(data.has_app_pwa_config).toBe(true);
});
it("sets `has_app_pwa_config` to true for a non '/' baseUrl", async () => {
const config = mockValidatedConfig({
outputTargets: [{ type: 'www', serviceWorker: { swDest: './tmp' } }],
});
const data = await telemetry.prepareData(coreCompiler, config, sys, 1000);
expect(data.has_app_pwa_config).toBe(true);
});
});
it('sends a component count when one is provided', async () => {
const COMPONENT_COUNT = 12;
const config = mockValidatedConfig({
outputTargets: [{ type: 'www' }],
});
const data = await telemetry.prepareData(coreCompiler, config, sys, 1000, COMPONENT_COUNT);
expect(data.component_count).toEqual(COMPONENT_COUNT);
});
});
describe('anonymizeConfigForTelemetry', () => {
let config: d.ValidatedConfig;
let sys: d.CompilerSystem;
beforeEach(() => {
sys = createSystem();
config = mockValidatedConfig({ sys });
});
it.each([
'rootDir',
'fsNamespace',
'packageJsonFilePath',
'namespace',
'srcDir',
'srcIndexHtml',
'buildLogFilePath',
'cacheDir',
'configPath',
'tsconfig',
])("should anonymize top-level string prop '%s'", (prop: keyof d.ValidatedConfig) => {
const anonymizedConfig = anonymizeConfigForTelemetry({
...config,
[prop]: "shouldn't see this!",
outputTargets: [],
});
expect(anonymizedConfig[prop]).toBe('omitted');
expect(anonymizedConfig.outputTargets).toEqual([]);
});
it.each([
'commonjs',
'devServer',
'env',
'logger',
'rollupConfig',
'sys',
'testing',
'tsCompilerOptions',
])("should remove objects under prop '%s'", (prop: keyof d.ValidatedConfig) => {
const anonymizedConfig = anonymizeConfigForTelemetry({ ...config, [prop]: {}, outputTargets: [] });
expect(anonymizedConfig.hasOwnProperty(prop)).toBe(false);
expect(anonymizedConfig.outputTargets).toEqual([]);
});
it('should retain outputTarget props on the keep list', () => {
const anonymizedConfig = anonymizeConfigForTelemetry({
...config,
outputTargets: [
{ type: WWW, baseUrl: 'https://example.com' },
{ type: DIST_HYDRATE_SCRIPT, external: ['beep', 'boop'], dir: 'shoud/go/away' },
{ type: DIST_CUSTOM_ELEMENTS },
{ type: DIST_CUSTOM_ELEMENTS, generateTypeDeclarations: true },
{ type: DIST, typesDir: 'my-types' },
],
});
expect(anonymizedConfig.outputTargets).toEqual([
{ type: WWW, baseUrl: 'omitted' },
{ type: DIST_HYDRATE_SCRIPT, external: ['beep', 'boop'], dir: 'omitted' },
{ type: DIST_CUSTOM_ELEMENTS },
{ type: DIST_CUSTOM_ELEMENTS, generateTypeDeclarations: true },
{ type: DIST, typesDir: 'omitted' },
]);
});
});
================================================
FILE: src/cli/test/ionic-config.spec.ts
================================================
import { mockCompilerSystem } from '@stencil/core/testing';
import { createSystem } from '../../compiler/sys/stencil-sys';
import { defaultConfig, readConfig, updateConfig, writeConfig } from '../ionic-config';
import { UUID_REGEX } from '../telemetry/helpers';
const UUID1 = '5588e0f0-02b5-4afa-8194-5d8f78683b36';
const UUID2 = 'e5609819-5c24-4fa2-8817-e05ca10b8cae';
describe('readConfig', () => {
const sys = mockCompilerSystem();
beforeEach(async () => {
await sys.removeFile(defaultConfig(sys));
});
it('should create a file if it does not exist', async () => {
const result = await sys.stat(defaultConfig(sys));
// expect the file to have been deleted by the test setup
expect(result.isFile).toBe(false);
const config = await readConfig(sys);
expect(Object.keys(config).join()).toBe('tokens.telemetry,telemetry.stencil');
});
it("should fix the telemetry token if it's a string, but an invalid UUID", async () => {
await writeConfig(sys, { 'telemetry.stencil': true, 'tokens.telemetry': 'aaaa' });
const result = await sys.stat(defaultConfig(sys));
expect(result.isFile).toBe(true);
const config = await readConfig(sys);
expect(Object.keys(config).join()).toBe('telemetry.stencil,tokens.telemetry');
expect(config['telemetry.stencil']).toBe(true);
expect(config['tokens.telemetry']).toMatch(UUID_REGEX);
});
it('handles a non-string telemetry token', async () => {
// our typings state that `tokens.telemetry` is of type `string | undefined`, but technically this value could be
// anything. use `undefined` to make the typings happy (this should cover all non-string telemetry tokens). the
// important thing here is that the value is _not_ a string for this test!
await writeConfig(sys, { 'telemetry.stencil': true, 'tokens.telemetry': undefined });
const config = await readConfig(sys);
expect(Object.keys(config).join()).toBe('telemetry.stencil,tokens.telemetry');
expect(config['telemetry.stencil']).toBe(true);
expect(config['tokens.telemetry']).toMatch(UUID_REGEX);
});
it('handles a non-existent telemetry token', async () => {
await writeConfig(sys, { 'telemetry.stencil': true });
const config = await readConfig(sys);
expect(Object.keys(config).join()).toBe('telemetry.stencil,tokens.telemetry');
expect(config['telemetry.stencil']).toBe(true);
expect(config['tokens.telemetry']).toMatch(UUID_REGEX);
});
it('should read a file if it exists', async () => {
await writeConfig(sys, { 'telemetry.stencil': true, 'tokens.telemetry': UUID1 });
const result = await sys.stat(defaultConfig(sys));
expect(result.isFile).toBe(true);
const config = await readConfig(sys);
expect(Object.keys(config).join()).toBe('telemetry.stencil,tokens.telemetry');
expect(config['telemetry.stencil']).toBe(true);
expect(config['tokens.telemetry']).toBe(UUID1);
});
});
describe('updateConfig', () => {
const sys = createSystem();
it('should edit a file', async () => {
await writeConfig(sys, { 'telemetry.stencil': true, 'tokens.telemetry': UUID1 });
const result = await sys.stat(defaultConfig(sys));
expect(result.isFile).toBe(true);
const configPre = await readConfig(sys);
expect(typeof configPre).toBe('object');
expect(Object.keys(configPre).join()).toBe('telemetry.stencil,tokens.telemetry');
expect(configPre['telemetry.stencil']).toBe(true);
expect(configPre['tokens.telemetry']).toBe(UUID1);
await updateConfig(sys, { 'telemetry.stencil': false, 'tokens.telemetry': UUID2 });
const configPost = await readConfig(sys);
expect(typeof configPost).toBe('object');
// Should keep the previous order
expect(Object.keys(configPost).join()).toBe('telemetry.stencil,tokens.telemetry');
expect(configPost['telemetry.stencil']).toBe(false);
expect(configPost['tokens.telemetry']).toBe(UUID2);
});
});
================================================
FILE: src/cli/test/parse-flags.spec.ts
================================================
import { toDashCase } from '@utils';
import { LogLevel } from '../../declarations';
import {
BOOLEAN_CLI_FLAGS,
BOOLEAN_STRING_CLI_FLAGS,
BooleanStringCLIFlag,
ConfigFlags,
NUMBER_CLI_FLAGS,
STRING_ARRAY_CLI_FLAGS,
STRING_CLI_FLAGS,
StringArrayCLIFlag,
} from '../config-flags';
import { Empty, parseEqualsArg, parseFlags } from '../parse-flags';
describe('parseFlags', () => {
it('should get known and unknown args', () => {
const args = ['serve', '--address', '127.0.0.1', '--potatoArgument', '--flimflammery', 'test.spec.ts'];
const flags = parseFlags(args);
expect(flags.task).toBe('serve');
expect(flags.args[0]).toBe('--address');
expect(flags.args[1]).toBe('127.0.0.1');
expect(flags.args[2]).toBe('--potatoArgument');
expect(flags.args[3]).toBe('--flimflammery');
expect(flags.args[4]).toBe('test.spec.ts');
expect(flags.knownArgs).toEqual(['--address', '127.0.0.1']);
expect(flags.unknownArgs[0]).toBe('--potatoArgument');
expect(flags.unknownArgs[1]).toBe('--flimflammery');
expect(flags.unknownArgs[2]).toBe('test.spec.ts');
});
it('should parse cli for dev server', () => {
// user command line args
// $ npm run serve --port 4444
// args.slice(2)
// [ 'serve', '--address', '127.0.0.1', '--port', '4444' ]
const args = ['serve', '--address', '127.0.0.1', '--port', '4444'];
const flags = parseFlags(args);
expect(flags.task).toBe('serve');
expect(flags.address).toBe('127.0.0.1');
expect(flags.port).toBe(4444);
expect(flags.knownArgs).toEqual(['--address', '127.0.0.1', '--port', '4444']);
});
it('should parse task', () => {
const flags = parseFlags(['build']);
expect(flags.task).toBe('build');
});
it('should parse no task', () => {
const flags = parseFlags(['--flag']);
expect(flags.task).toBe(null);
});
/**
* these comprehensive tests of all the supported boolean args serve as
* regression tests against duplicating any of the arguments in the arrays.
* Because of the way that the arg parsing algorithm works having a dupe
* will result in a value like `[true, true]` being set on ConfigFlags, which
* will cause these tests to start failing.
*/
describe.each(BOOLEAN_CLI_FLAGS)('should parse boolean flag %s', (cliArg) => {
it('should parse arg', () => {
const flags = parseFlags([`--${cliArg}`]);
expect(flags.knownArgs).toEqual([`--${cliArg}`]);
expect(flags[cliArg]).toBe(true);
});
it(`should parse --no${cliArg}`, () => {
const negativeFlag = '--no' + cliArg.charAt(0).toUpperCase() + cliArg.slice(1);
const flags = parseFlags([negativeFlag]);
expect(flags.knownArgs).toEqual([negativeFlag]);
expect(flags[cliArg]).toBe(false);
});
it(`should override --${cliArg} with --no${cliArg}`, () => {
const negativeFlag = '--no' + cliArg.charAt(0).toUpperCase() + cliArg.slice(1);
const flags = parseFlags([`--${cliArg}`, negativeFlag]);
expect(flags.knownArgs).toEqual([`--${cliArg}`, negativeFlag]);
expect(flags[cliArg]).toBe(false);
});
it('should not set value if not present', () => {
const flags = parseFlags([]);
expect(flags.knownArgs).toEqual([]);
expect(flags[cliArg]).toBe(undefined);
});
it.each([true, false])(`should set the value with --${cliArg}=%p`, (value) => {
const flags = parseFlags([`--${cliArg}=${value}`]);
expect(flags.knownArgs).toEqual([`--${cliArg}`, String(value)]);
expect(flags[cliArg]).toBe(value);
});
});
describe.each(STRING_CLI_FLAGS)('should parse string flag %s', (cliArg) => {
it(`should parse "--${cliArg} value"`, () => {
const flags = parseFlags([`--${cliArg}`, 'test-value']);
expect(flags.knownArgs).toEqual([`--${cliArg}`, 'test-value']);
expect(flags.unknownArgs).toEqual([]);
expect(flags[cliArg]).toBe('test-value');
});
it(`should parse "--${cliArg}=value"`, () => {
const flags = parseFlags([`--${cliArg}=path/to/file.js`]);
expect(flags.knownArgs).toEqual([`--${cliArg}`, 'path/to/file.js']);
expect(flags.unknownArgs).toEqual([]);
expect(flags[cliArg]).toBe('path/to/file.js');
});
it(`should parse "--${toDashCase(cliArg)} value"`, () => {
const flags = parseFlags([`--${toDashCase(cliArg)}`, 'path/to/file.js']);
expect(flags.knownArgs).toEqual([`--${toDashCase(cliArg)}`, 'path/to/file.js']);
expect(flags.unknownArgs).toEqual([]);
expect(flags[cliArg]).toBe('path/to/file.js');
});
it(`should parse "--${toDashCase(cliArg)}=value"`, () => {
const flags = parseFlags([`--${toDashCase(cliArg)}=path/to/file.js`]);
expect(flags.knownArgs).toEqual([`--${toDashCase(cliArg)}`, 'path/to/file.js']);
expect(flags.unknownArgs).toEqual([]);
expect(flags[cliArg]).toBe('path/to/file.js');
});
});
it.each(NUMBER_CLI_FLAGS)('should parse number flag %s', (cliArg) => {
const flags = parseFlags([`--${cliArg}`, '42']);
expect(flags.knownArgs).toEqual([`--${cliArg}`, '42']);
expect(flags.unknownArgs).toEqual([]);
expect(flags[cliArg]).toBe(42);
});
it('should override --config with second --config', () => {
const args = ['--config', '/config-1.js', '--config', '/config-2.js'];
const flags = parseFlags(args);
expect(flags.config).toBe('/config-2.js');
});
describe.each(BOOLEAN_STRING_CLI_FLAGS)('boolean-string flag - %s', (cliArg: BooleanStringCLIFlag) => {
it('parses a boolean-string flag as a boolean with no arg', () => {
const args = [`--${cliArg}`];
const flags = parseFlags(args);
expect(flags[cliArg]).toBe(true);
expect(flags.knownArgs).toEqual([`--${cliArg}`]);
});
it(`parses a boolean-string flag as a falsy boolean with "no" arg - --no-${cliArg}`, () => {
const args = [`--no-${cliArg}`];
const flags = parseFlags(args);
expect(flags[cliArg]).toBe(false);
expect(flags.knownArgs).toEqual([`--no-${cliArg}`]);
});
it(`parses a boolean-string flag as a falsy boolean with "no" arg - --no${
cliArg.charAt(0).toUpperCase() + cliArg.slice(1)
}`, () => {
const negativeFlag = '--no' + cliArg.charAt(0).toUpperCase() + cliArg.slice(1);
const flags = parseFlags([negativeFlag]);
expect(flags[cliArg]).toBe(false);
expect(flags.knownArgs).toEqual([negativeFlag]);
});
it('parses a boolean-string flag as a string with a string arg', () => {
const args = [`--${cliArg}`, 'shell'];
const flags = parseFlags(args);
expect(flags[cliArg]).toBe('shell');
expect(flags.knownArgs).toEqual([`--${cliArg}`, 'shell']);
});
it('parses a boolean-string flag as a string with a string arg using equality', () => {
const args = [`--${cliArg}=shell`];
const flags = parseFlags(args);
expect(flags[cliArg]).toBe('shell');
expect(flags.knownArgs).toEqual([`--${cliArg}`, 'shell']);
});
});
describe.each(['info', 'warn', 'error', 'debug'])('logLevel %s', (level) => {
it("should parse '--logLevel %s'", () => {
const args = ['--logLevel', level];
const flags = parseFlags(args);
expect(flags.logLevel).toBe(level);
});
it('should parse --logLevel=%s', () => {
const args = [`--logLevel=${level}`];
const flags = parseFlags(args);
expect(flags.logLevel).toBe(level);
});
it("should parse '--log-level %s'", () => {
const flags = parseFlags(['--log-level', level]);
expect(flags.logLevel).toBe(level);
});
it('should parse --log-level=%s', () => {
const flags = parseFlags([`--log-level=${level}`]);
expect(flags.logLevel).toBe(level);
});
});
/**
* maxWorkers is (as of this writing) our only StringNumberCLIArg, meaning it
* may be a string (like "50%") or a number (like 4). For this reason we have
* some tests just for it.
*/
describe('maxWorkers', () => {
it.each([
['--maxWorkers', '4'],
['--maxWorkers=4'],
['--max-workers', '4'],
['--maxWorkers', '4e+0'],
['--maxWorkers', '40e-1'],
])('should parse %p, %p', (...args) => {
const flags = parseFlags(args);
expect(flags.maxWorkers).toBe(4);
});
it('should parse --maxWorkers 4', () => {
const flags = parseFlags(['--maxWorkers', '4']);
expect(flags.maxWorkers).toBe(4);
});
it('should parse --maxWorkers=4', () => {
const flags = parseFlags(['--maxWorkers=4']);
expect(flags.maxWorkers).toBe(4);
});
it('should parse --max-workers 4', () => {
const flags = parseFlags(['--max-workers', '4']);
expect(flags.maxWorkers).toBe(4);
});
it('should parse --maxWorkers=50%', function () {
// see https://jestjs.io/docs/27.x/cli#--maxworkersnumstring
const flags = parseFlags(['--maxWorkers=50%']);
expect(flags.maxWorkers).toBe('50%');
});
it('should parse --max-workers=1', () => {
const flags = parseFlags(['--max-workers=1']);
expect(flags.maxWorkers).toBe(1);
});
it('should not parse --max-workers', () => {
const flags = parseFlags([]);
expect(flags.maxWorkers).toBe(undefined);
});
});
describe('aliases', () => {
describe('-p (alias for port)', () => {
it('should parse -p=4444', () => {
const flags = parseFlags(['-p=4444']);
expect(flags.port).toBe(4444);
});
it('should parse -p 4444', () => {
const flags = parseFlags(['-p', '4444']);
expect(flags.port).toBe(4444);
});
});
it('should parse -h (alias for help)', () => {
const flags = parseFlags(['-h']);
expect(flags.help).toBe(true);
});
it('should parse -v (alias for version)', () => {
const flags = parseFlags(['-v']);
expect(flags.version).toBe(true);
});
describe('-c alias for config', () => {
it('should parse -c /my-config.js', () => {
const flags = parseFlags(['-c', '/my-config.js']);
expect(flags.config).toBe('/my-config.js');
expect(flags.knownArgs).toEqual(['--config', '/my-config.js']);
});
it('should parse -c=/my-config.js', () => {
const flags = parseFlags(['-c=/my-config.js']);
expect(flags.config).toBe('/my-config.js');
expect(flags.knownArgs).toEqual(['--config', '/my-config.js']);
});
});
describe('Jest aliases', () => {
it.each([
['w', 'maxWorkers', '4'],
['t', 'testNamePattern', 'testname'],
])('should support the string Jest alias %p for %p', (alias, fullArgument, value) => {
const flags = parseFlags([`-${alias}`, value]);
expect(flags.knownArgs).toEqual([`--${fullArgument}`, value]);
expect(flags.unknownArgs).toHaveLength(0);
});
it.each([
['w', 'maxWorkers', '4'],
['t', 'testNamePattern', 'testname'],
])('should support the string Jest alias %p for %p in an AliasEqualsArg', (alias, fullArgument, value) => {
const flags = parseFlags([`-${alias}=${value}`]);
expect(flags.knownArgs).toEqual([`--${fullArgument}`, value]);
expect(flags.unknownArgs).toHaveLength(0);
});
it.each<[string, keyof ConfigFlags]>([
['b', 'bail'],
['e', 'expand'],
['o', 'onlyChanged'],
['f', 'onlyFailures'],
['i', 'runInBand'],
['u', 'updateSnapshot'],
])('should support the boolean Jest alias %p for %p', (alias, fullArgument) => {
const flags = parseFlags([`-${alias}`]);
expect(flags.knownArgs).toEqual([`--${fullArgument}`]);
expect(flags[fullArgument]).toBe(true);
expect(flags.unknownArgs).toHaveLength(0);
});
});
});
it('should parse many', () => {
const args = ['-v', '--help', '-c=./myconfig.json'];
const flags = parseFlags(args);
expect(flags.version).toBe(true);
expect(flags.help).toBe(true);
expect(flags.config).toBe('./myconfig.json');
});
describe('parseEqualsArg', () => {
it.each([
['--fooBar=baz', '--fooBar', 'baz'],
['--foo-bar=4', '--foo-bar', '4'],
['--fooBar=twenty=3*4', '--fooBar', 'twenty=3*4'],
['--fooBar', '--fooBar', Empty],
['--foo-bar', '--foo-bar', Empty],
['--foo-bar=""', '--foo-bar', '""'],
])('should parse %s correctly', (testArg, expectedArg, expectedValue) => {
const [arg, value] = parseEqualsArg(testArg);
expect(arg).toBe(expectedArg);
expect(value).toEqual(expectedValue);
});
});
describe.each(STRING_ARRAY_CLI_FLAGS)('should parse string flag %s', (cliArg: StringArrayCLIFlag) => {
it(`should parse single value: "--${cliArg} test-value"`, () => {
const flags = parseFlags([`--${cliArg}`, 'test-value']);
expect(flags.knownArgs).toEqual([`--${cliArg}`, 'test-value']);
expect(flags.unknownArgs).toEqual([]);
expect(flags[cliArg]).toEqual(['test-value']);
});
it(`should parse multiple values: "--${cliArg} test-value"`, () => {
const flags = parseFlags([`--${cliArg}`, 'test-value', `--${cliArg}`, 'second-test-value']);
expect(flags.knownArgs).toEqual([`--${cliArg}`, 'test-value', `--${cliArg}`, 'second-test-value']);
expect(flags.unknownArgs).toEqual([]);
expect(flags[cliArg]).toEqual(['test-value', 'second-test-value']);
});
it(`should parse "--${cliArg}=value"`, () => {
const flags = parseFlags([`--${cliArg}=path/to/file.js`]);
expect(flags.knownArgs).toEqual([`--${cliArg}`, 'path/to/file.js']);
expect(flags.unknownArgs).toEqual([]);
expect(flags[cliArg]).toEqual(['path/to/file.js']);
});
it(`should parse multiple values: "--${cliArg}=test-value"`, () => {
const flags = parseFlags([`--${cliArg}=test-value`, `--${cliArg}=second-test-value`]);
expect(flags.knownArgs).toEqual([`--${cliArg}`, 'test-value', `--${cliArg}`, 'second-test-value']);
expect(flags.unknownArgs).toEqual([]);
expect(flags[cliArg]).toEqual(['test-value', 'second-test-value']);
});
it(`should parse "--${toDashCase(cliArg)} value"`, () => {
const flags = parseFlags([`--${toDashCase(cliArg)}`, 'path/to/file.js']);
expect(flags.knownArgs).toEqual([`--${toDashCase(cliArg)}`, 'path/to/file.js']);
expect(flags.unknownArgs).toEqual([]);
expect(flags[cliArg]).toEqual(['path/to/file.js']);
});
it(`should parse multiple values: "--${toDashCase(cliArg)} test-value"`, () => {
const flags = parseFlags([
`--${toDashCase(cliArg)}`,
'test-value',
`--${toDashCase(cliArg)}`,
'second-test-value',
]);
expect(flags.knownArgs).toEqual([
`--${toDashCase(cliArg)}`,
'test-value',
`--${toDashCase(cliArg)}`,
'second-test-value',
]);
expect(flags.unknownArgs).toEqual([]);
expect(flags[cliArg]).toEqual(['test-value', 'second-test-value']);
});
it(`should parse "--${toDashCase(cliArg)}=value"`, () => {
const flags = parseFlags([`--${toDashCase(cliArg)}=path/to/file.js`]);
expect(flags.knownArgs).toEqual([`--${toDashCase(cliArg)}`, 'path/to/file.js']);
expect(flags.unknownArgs).toEqual([]);
expect(flags[cliArg]).toEqual(['path/to/file.js']);
});
it(`should parse multiple values: "--${toDashCase(cliArg)}=test-value"`, () => {
const flags = parseFlags([`--${toDashCase(cliArg)}=test-value`, `--${toDashCase(cliArg)}=second-test-value`]);
expect(flags.knownArgs).toEqual([
`--${toDashCase(cliArg)}`,
'test-value',
`--${toDashCase(cliArg)}`,
'second-test-value',
]);
expect(flags.unknownArgs).toEqual([]);
expect(flags[cliArg]).toEqual(['test-value', 'second-test-value']);
});
});
describe('error reporting', () => {
it('should throw if you pass no argument to a string flag', () => {
expect(() => {
parseFlags(['--cacheDirectory', '--someOtherFlag']);
}).toThrow('when parsing CLI flag "--cacheDirectory": expected a string argument but received nothing');
});
it('should throw if you pass no argument to a string array flag', () => {
expect(() => {
parseFlags(['--reporters', '--someOtherFlag']);
}).toThrow('when parsing CLI flag "--reporters": expected a string argument but received nothing');
});
it('should throw if you pass no argument to a number flag', () => {
expect(() => {
parseFlags(['--port', '--someOtherFlag']);
}).toThrow('when parsing CLI flag "--port": expected a number argument but received nothing');
});
it('should throw if you pass a non-number argument to a number flag', () => {
expect(() => {
parseFlags(['--port', 'stringy']);
}).toThrow('when parsing CLI flag "--port": expected a number but received "stringy"');
});
it('should throw if you pass a bad number argument to a number flag', () => {
expect(() => {
parseFlags(['--port=NaN']);
}).toThrow('when parsing CLI flag "--port": expected a number but received "NaN"');
});
it('should throw if you pass no argument to a string/number flag', () => {
expect(() => {
parseFlags(['--maxWorkers']);
}).toThrow('when parsing CLI flag "--maxWorkers": expected a string or a number but received nothing');
});
it('should throw if you pass an invalid log level for --logLevel', () => {
expect(() => {
parseFlags(['--logLevel', 'potato']);
}).toThrow('when parsing CLI flag "--logLevel": expected to receive a valid log level but received "potato"');
});
it('should throw if you pass no argument to --logLevel', () => {
expect(() => {
parseFlags(['--logLevel']);
}).toThrow('when parsing CLI flag "--logLevel": expected to receive a valid log level but received nothing');
});
});
});
================================================
FILE: src/cli/test/run.spec.ts
================================================
import * as coreCompiler from '@stencil/core/compiler';
import { mockCompilerSystem, mockConfig, mockLogger as createMockLogger } from '@stencil/core/testing';
import type * as d from '../../declarations';
import { createTestingSystem } from '../../testing/testing-sys';
import { createConfigFlags } from '../config-flags';
import * as ParseFlags from '../parse-flags';
import { run, runTask } from '../run';
import * as BuildTask from '../task-build';
import * as DocsTask from '../task-docs';
import * as GenerateTask from '../task-generate';
import * as HelpTask from '../task-help';
import * as PrerenderTask from '../task-prerender';
import * as ServeTask from '../task-serve';
import * as TelemetryTask from '../task-telemetry';
import * as TestTask from '../task-test';
describe('run', () => {
describe('run()', () => {
let cliInitOptions: d.CliInitOptions;
let mockLogger: d.Logger;
let mockSystem: d.CompilerSystem;
let parseFlagsSpy: jest.SpyInstance<
ReturnType,
Parameters
>;
beforeEach(() => {
mockLogger = createMockLogger();
mockSystem = createTestingSystem();
cliInitOptions = {
args: [],
logger: mockLogger,
sys: mockSystem,
};
parseFlagsSpy = jest.spyOn(ParseFlags, 'parseFlags');
parseFlagsSpy.mockReturnValue(
createConfigFlags({
// use the 'help' task as a reasonable default for all calls to this function.
// code paths that require a different task can always override this value as needed.
task: 'help',
}),
);
});
afterEach(() => {
parseFlagsSpy.mockRestore();
});
describe('help task', () => {
let taskHelpSpy: jest.SpyInstance, Parameters>;
beforeEach(() => {
taskHelpSpy = jest.spyOn(HelpTask, 'taskHelp');
taskHelpSpy.mockReturnValue(Promise.resolve());
});
afterEach(() => {
taskHelpSpy.mockRestore();
});
it("calls the help task when the 'task' field is set to 'help'", async () => {
await run(cliInitOptions);
expect(taskHelpSpy).toHaveBeenCalledTimes(1);
expect(taskHelpSpy).toHaveBeenCalledWith(
{
task: 'help',
args: [],
knownArgs: [],
unknownArgs: [],
},
mockLogger,
mockSystem,
);
taskHelpSpy.mockRestore();
});
it("calls the help task when the 'task' field is set to null", async () => {
parseFlagsSpy.mockReturnValue(
createConfigFlags({
task: null,
}),
);
await run(cliInitOptions);
expect(taskHelpSpy).toHaveBeenCalledTimes(1);
expect(taskHelpSpy).toHaveBeenCalledWith(
{
task: 'help',
args: [],
knownArgs: [],
unknownArgs: [],
},
mockLogger,
mockSystem,
);
taskHelpSpy.mockRestore();
});
it("calls the help task when the 'help' field is set on flags", async () => {
parseFlagsSpy.mockReturnValue(
createConfigFlags({
help: true,
}),
);
await run(cliInitOptions);
expect(taskHelpSpy).toHaveBeenCalledTimes(1);
expect(taskHelpSpy).toHaveBeenCalledWith(
{
task: 'help',
args: [],
unknownArgs: [],
knownArgs: [],
},
mockLogger,
mockSystem,
);
taskHelpSpy.mockRestore();
});
});
});
describe('runTask()', () => {
let sys: d.CompilerSystem;
let unvalidatedConfig: d.UnvalidatedConfig;
let taskBuildSpy: jest.SpyInstance, Parameters>;
let taskDocsSpy: jest.SpyInstance, Parameters>;
let taskGenerateSpy: jest.SpyInstance<
ReturnType,
Parameters
>;
let taskHelpSpy: jest.SpyInstance, Parameters>;
let taskPrerenderSpy: jest.SpyInstance<
ReturnType,
Parameters
>;
let taskServeSpy: jest.SpyInstance, Parameters>;
let taskTelemetrySpy: jest.SpyInstance<
ReturnType,
Parameters
>;
let taskTestSpy: jest.SpyInstance, Parameters>;
beforeEach(() => {
sys = mockCompilerSystem();
sys.exit = jest.fn();
unvalidatedConfig = mockConfig({ outputTargets: [], sys, fsNamespace: 'testing' });
taskBuildSpy = jest.spyOn(BuildTask, 'taskBuild');
taskBuildSpy.mockResolvedValue();
taskDocsSpy = jest.spyOn(DocsTask, 'taskDocs');
taskDocsSpy.mockResolvedValue();
taskGenerateSpy = jest.spyOn(GenerateTask, 'taskGenerate');
taskGenerateSpy.mockResolvedValue();
taskHelpSpy = jest.spyOn(HelpTask, 'taskHelp');
taskHelpSpy.mockResolvedValue();
taskPrerenderSpy = jest.spyOn(PrerenderTask, 'taskPrerender');
taskPrerenderSpy.mockResolvedValue();
taskServeSpy = jest.spyOn(ServeTask, 'taskServe');
taskServeSpy.mockResolvedValue();
taskTelemetrySpy = jest.spyOn(TelemetryTask, 'taskTelemetry');
taskTelemetrySpy.mockResolvedValue();
taskTestSpy = jest.spyOn(TestTask, 'taskTest');
taskTestSpy.mockResolvedValue();
});
afterEach(() => {
taskBuildSpy.mockRestore();
taskDocsSpy.mockRestore();
taskGenerateSpy.mockRestore();
taskHelpSpy.mockRestore();
taskPrerenderSpy.mockRestore();
taskServeSpy.mockRestore();
taskTelemetrySpy.mockRestore();
taskTestSpy.mockRestore();
});
describe('default configuration', () => {
describe('sys property', () => {
it('uses the sys argument if one is provided', async () => {
// remove the `CompilerSystem` on the config, just to be sure we don't accidentally use it
unvalidatedConfig.sys = undefined;
await runTask(coreCompiler, unvalidatedConfig, 'build', sys);
const validated = coreCompiler.validateConfig(unvalidatedConfig, { sys });
// first validate there was one call, and that call had two arguments
expect(taskBuildSpy).toHaveBeenCalledTimes(1);
expect(taskBuildSpy).toHaveBeenCalledWith(coreCompiler, validated.config);
const compilerSystemUsed: d.CompilerSystem = taskBuildSpy.mock.calls[0][1].sys;
expect(compilerSystemUsed).toBe(sys);
});
});
});
it('calls the build task', async () => {
await runTask(coreCompiler, unvalidatedConfig, 'build', sys);
const validated = coreCompiler.validateConfig(unvalidatedConfig, {});
expect(taskBuildSpy).toHaveBeenCalledTimes(1);
expect(taskBuildSpy).toHaveBeenCalledWith(coreCompiler, validated.config);
});
it('calls the docs task', async () => {
await runTask(coreCompiler, unvalidatedConfig, 'docs', sys);
const validated = coreCompiler.validateConfig(unvalidatedConfig, {});
expect(taskDocsSpy).toHaveBeenCalledTimes(1);
expect(taskDocsSpy).toHaveBeenCalledWith(coreCompiler, validated.config);
});
describe('generate task', () => {
it("calls the generate task for the argument 'generate'", async () => {
await runTask(coreCompiler, unvalidatedConfig, 'generate', sys);
const validated = coreCompiler.validateConfig(unvalidatedConfig, {});
expect(taskGenerateSpy).toHaveBeenCalledTimes(1);
expect(taskGenerateSpy).toHaveBeenCalledWith(validated.config);
});
it("calls the generate task for the argument 'g'", async () => {
await runTask(coreCompiler, unvalidatedConfig, 'g', sys);
const validated = coreCompiler.validateConfig(unvalidatedConfig, {});
expect(taskGenerateSpy).toHaveBeenCalledTimes(1);
expect(taskGenerateSpy).toHaveBeenCalledWith(validated.config);
});
});
it('calls the help task', async () => {
await runTask(coreCompiler, unvalidatedConfig, 'help', sys);
const validated = coreCompiler.validateConfig(unvalidatedConfig, {});
expect(taskHelpSpy).toHaveBeenCalledTimes(1);
expect(taskHelpSpy).toHaveBeenCalledWith(validated.config.flags, validated.config.logger, sys);
});
it('calls the prerender task', async () => {
await runTask(coreCompiler, unvalidatedConfig, 'prerender', sys);
const validated = coreCompiler.validateConfig(unvalidatedConfig, {});
expect(taskPrerenderSpy).toHaveBeenCalledTimes(1);
expect(taskPrerenderSpy).toHaveBeenCalledWith(coreCompiler, validated.config);
});
it('calls the serve task', async () => {
await runTask(coreCompiler, unvalidatedConfig, 'serve', sys);
expect(taskServeSpy).toHaveBeenCalledTimes(1);
expect(taskServeSpy).toHaveBeenCalledWith(coreCompiler.validateConfig(unvalidatedConfig, {}).config);
});
describe('telemetry task', () => {
it('calls the telemetry task when a compiler system is present', async () => {
await runTask(coreCompiler, unvalidatedConfig, 'telemetry', sys);
const validated = coreCompiler.validateConfig(unvalidatedConfig, {});
expect(taskTelemetrySpy).toHaveBeenCalledTimes(1);
expect(taskTelemetrySpy).toHaveBeenCalledWith(validated.config.flags, sys, validated.config.logger);
});
});
it('calls the test task', async () => {
await runTask(coreCompiler, unvalidatedConfig, 'test', sys);
expect(taskTestSpy).toHaveBeenCalledTimes(1);
expect(taskTestSpy).toHaveBeenCalledWith(coreCompiler.validateConfig(unvalidatedConfig, {}).config);
});
it('defaults to the help task for an unaccounted for task name', async () => {
// info is a valid task name, but isn't used in the `switch` statement of `runTask`
await runTask(coreCompiler, unvalidatedConfig, 'info', sys);
const validated = coreCompiler.validateConfig(unvalidatedConfig, {});
expect(taskHelpSpy).toHaveBeenCalledTimes(1);
expect(taskHelpSpy).toHaveBeenCalledWith(validated.config.flags, validated.config.logger, sys);
});
it('defaults to the provided task if no flags exist on the provided config', async () => {
unvalidatedConfig = mockConfig({ flags: undefined, sys });
await runTask(coreCompiler, unvalidatedConfig, 'help', sys);
const validated = coreCompiler.validateConfig(unvalidatedConfig, {});
expect(taskHelpSpy).toHaveBeenCalledTimes(1);
expect(taskHelpSpy).toHaveBeenCalledWith(createConfigFlags({ task: 'help' }), validated.config.logger, sys);
});
});
});
================================================
FILE: src/cli/test/task-generate.spec.ts
================================================
import { mockCompilerSystem, mockValidatedConfig } from '@stencil/core/testing';
import type * as d from '../../declarations';
import * as utils from '../../utils/validation';
import { createConfigFlags } from '../config-flags';
import { BoilerplateFile, getBoilerplateByExtension, taskGenerate } from '../task-generate';
const promptMock = jest.fn().mockResolvedValue('my-component');
jest.mock('prompts', () => ({
prompt: promptMock,
}));
let formatToPick = 'css';
const setup = async (plugins: any[] = []) => {
const sys = mockCompilerSystem();
const config: d.ValidatedConfig = mockValidatedConfig({
configPath: '/testing-path',
flags: createConfigFlags({ task: 'generate' }),
srcDir: '/src',
sys,
plugins,
});
// set up some mocks / spies
config.sys.exit = jest.fn();
const errorSpy = jest.spyOn(config.logger, 'error');
const validateTagSpy = jest.spyOn(utils, 'validateComponentTag').mockReturnValue(undefined);
// mock prompt usage: tagName and filesToGenerate are the keys used for
// different calls, so we can cheat here and just do a single
// mockResolvedValue
let format = formatToPick;
promptMock.mockImplementation((params) => {
if (params.name === 'sassFormat') {
format = 'sass';
return { sassFormat: 'sass' };
}
return {
tagName: 'my-component',
filesToGenerate: [format, 'spec.tsx', 'e2e.ts'],
};
});
return { config, errorSpy, validateTagSpy };
};
/**
* Little test helper function which just temporarily silences
* console.log calls, so we can avoid spewing a bunch of stuff.
* @param config the user-supplied config to forward to `taskGenerate`
*/
async function silentGenerate(config: d.ValidatedConfig): Promise {
const tmp = console.log;
console.log = jest.fn();
await taskGenerate(config);
console.log = tmp;
}
describe('generate task', () => {
afterEach(() => {
jest.restoreAllMocks();
jest.clearAllMocks();
jest.resetModules();
formatToPick = 'css';
});
afterAll(() => {
jest.resetAllMocks();
});
it('should exit with an error if no `configPath` is supplied', async () => {
const { config, errorSpy } = await setup();
config.configPath = undefined;
await taskGenerate(config);
expect(config.sys.exit).toHaveBeenCalledWith(1);
expect(errorSpy).toHaveBeenCalledWith(
'Please run this command in your root directory (i. e. the one containing stencil.config.ts).',
);
});
it('should exit with an error if no `srcDir` is supplied', async () => {
const { config, errorSpy } = await setup();
config.srcDir = undefined;
await taskGenerate(config);
expect(config.sys.exit).toHaveBeenCalledWith(1);
expect(errorSpy).toHaveBeenCalledWith("Stencil's srcDir was not specified.");
});
it('should exit with an error if the component name does not validate', async () => {
const { config, errorSpy, validateTagSpy } = await setup();
validateTagSpy.mockReturnValue('error error error');
await taskGenerate(config);
expect(config.sys.exit).toHaveBeenCalledWith(1);
expect(errorSpy).toHaveBeenCalledWith('error error error');
});
it.each([true, false])('should create a directory for the generated components', async (includeTests) => {
const { config } = await setup();
if (!includeTests) {
promptMock.mockResolvedValue({
tagName: 'my-component',
// simulate the user picking only the css option
filesToGenerate: ['css'],
});
}
const createDirSpy = jest.spyOn(config.sys, 'createDir');
await silentGenerate(config);
expect(createDirSpy).toHaveBeenCalledWith(
includeTests ? `${config.srcDir}/components/my-component/test` : `${config.srcDir}/components/my-component`,
{ recursive: true },
);
});
it('should generate the files the user picked', async () => {
const { config } = await setup();
const writeFileSpy = jest.spyOn(config.sys, 'writeFile');
await silentGenerate(config);
const userChoices: ReadonlyArray = [
{ extension: 'tsx', path: '/src/components/my-component/my-component.tsx' },
{ extension: 'css', path: '/src/components/my-component/my-component.css' },
{ extension: 'spec.tsx', path: '/src/components/my-component/test/my-component.spec.tsx' },
{ extension: 'e2e.ts', path: '/src/components/my-component/test/my-component.e2e.ts' },
];
userChoices.forEach((file) => {
expect(writeFileSpy).toHaveBeenCalledWith(
file.path,
getBoilerplateByExtension('my-component', file.extension, true, 'css'),
);
});
});
it('should error without writing anything if a to-be-generated file is already present', async () => {
const { config, errorSpy } = await setup();
jest.spyOn(config.sys, 'readFile').mockResolvedValue('some file contents');
await silentGenerate(config);
expect(errorSpy).toHaveBeenCalledWith(
'Generating code would overwrite the following files:',
'\t/src/components/my-component/my-component.tsx',
'\t/src/components/my-component/my-component.css',
'\t/src/components/my-component/test/my-component.spec.tsx',
'\t/src/components/my-component/test/my-component.e2e.ts',
);
expect(config.sys.exit).toHaveBeenCalledWith(1);
});
it('should generate files for sass projects', async () => {
const { config } = await setup([{ name: 'sass' }]);
const writeFileSpy = jest.spyOn(config.sys, 'writeFile');
await silentGenerate(config);
const userChoices: ReadonlyArray = [
{ extension: 'tsx', path: '/src/components/my-component/my-component.tsx' },
{ extension: 'sass', path: '/src/components/my-component/my-component.sass' },
{ extension: 'spec.tsx', path: '/src/components/my-component/test/my-component.spec.tsx' },
{ extension: 'e2e.ts', path: '/src/components/my-component/test/my-component.e2e.ts' },
];
userChoices.forEach((file) => {
expect(writeFileSpy).toHaveBeenCalledWith(
file.path,
getBoilerplateByExtension('my-component', file.extension, true, 'sass'),
);
});
});
it('should generate files for less projects', async () => {
formatToPick = 'less';
const { config } = await setup([{ name: 'less' }]);
const writeFileSpy = jest.spyOn(config.sys, 'writeFile');
await silentGenerate(config);
const userChoices: ReadonlyArray = [
{ extension: 'tsx', path: '/src/components/my-component/my-component.tsx' },
{ extension: 'less', path: '/src/components/my-component/my-component.less' },
{ extension: 'spec.tsx', path: '/src/components/my-component/test/my-component.spec.tsx' },
{ extension: 'e2e.ts', path: '/src/components/my-component/test/my-component.e2e.ts' },
];
userChoices.forEach((file) => {
expect(writeFileSpy).toHaveBeenCalledWith(
file.path,
getBoilerplateByExtension('my-component', file.extension, true, 'less'),
);
});
});
});
================================================
FILE: src/client/client-build.ts
================================================
import { BUILD } from '@app-data';
import type * as d from '../declarations';
export const Build: d.UserBuildConditionals = {
isDev: BUILD.isDev ? true : false,
isBrowser: true,
isServer: false,
isTesting: BUILD.isTesting ? true : false,
};
================================================
FILE: src/client/client-host-ref.ts
================================================
import { BUILD } from '@app-data';
import { CMP_FLAGS } from '@utils/constants';
import { reWireGetterSetter } from '@utils/es2022-rewire-class-members';
import type * as d from '../declarations';
/**
* Given a {@link d.RuntimeRef} retrieve the corresponding {@link d.HostRef}
*
* @param ref the runtime ref of interest
* @returns the Host reference (if found) or undefined
*/
export const getHostRef = (ref: d.RuntimeRef): d.HostRef | undefined => {
if (ref.__stencil__getHostRef) {
return ref.__stencil__getHostRef();
}
return undefined;
};
/**
* Register a lazy instance with the {@link hostRefs} object so it's
* corresponding {@link d.HostRef} can be retrieved later.
*
* @param lazyInstance the lazy instance of interest
* @param hostRef that instances `HostRef` object
*/
export const registerInstance = (lazyInstance: any, hostRef: d.HostRef) => {
if (!hostRef) return;
lazyInstance.__stencil__getHostRef = () => hostRef;
hostRef.$lazyInstance$ = lazyInstance;
if (hostRef.$cmpMeta$.$flags$ & CMP_FLAGS.hasModernPropertyDecls && (BUILD.state || BUILD.prop)) {
reWireGetterSetter(lazyInstance, hostRef);
}
};
/**
* Register a host element for a Stencil component, setting up various metadata
* and callbacks based on {@link BUILD} flags as well as the component's runtime
* metadata.
*
* @param hostElement the host element to register
* @param cmpMeta runtime metadata for that component
* @returns a reference to the host ref WeakMap
*/
export const registerHost = (hostElement: d.HostElement, cmpMeta: d.ComponentRuntimeMeta) => {
const hostRef: d.HostRef = {
$flags$: 0,
$hostElement$: hostElement,
$cmpMeta$: cmpMeta,
$instanceValues$: new Map(),
$serializerValues$: new Map(),
};
if (BUILD.isDev) {
hostRef.$renderCount$ = 0;
}
if (BUILD.method && BUILD.lazyLoad) {
hostRef.$onInstancePromise$ = new Promise((r) => (hostRef.$onInstanceResolve$ = r));
}
if (BUILD.asyncLoading) {
hostRef.$onReadyPromise$ = new Promise((r) => (hostRef.$onReadyResolve$ = r));
hostElement['s-p'] = [];
hostElement['s-rc'] = [];
}
if (BUILD.lazyLoad) {
hostRef.$fetchedCbList$ = [];
}
const ref = hostRef;
hostElement.__stencil__getHostRef = () => ref;
if (!BUILD.lazyLoad && cmpMeta.$flags$ & CMP_FLAGS.hasModernPropertyDecls && (BUILD.state || BUILD.prop)) {
reWireGetterSetter(hostElement, hostRef);
}
return ref;
};
export const isMemberInElement = (elm: any, memberName: string) => memberName in elm;
================================================
FILE: src/client/client-load-module.ts
================================================
import { BUILD } from '@app-data';
import type * as d from '../declarations';
import { consoleDevError, consoleError } from './client-log';
export const cmpModules = /*@__PURE__*/ new Map();
/**
* We need to separate out this prefix so that Esbuild doesn't try to resolve
* the below, but instead retains a dynamic `import()` statement in the
* emitted code.
*
* See here for details https://esbuild.github.io/api/#non-analyzable-imports
*
* We need to do this in order to prevent Esbuild from analyzing / transforming
* the input. However some _other_ bundlers will _not_ work with such an import
* if it _lacks_ a leading `"./"`, so we thus we have to do a little dance
* where here in the source code it must be like this, so that an undesirable
* transformation that Esbuild would otherwise carry out doesn't occur, but we
* actually need to then manually edit the bundled Esbuild code later on to fix
* that. We do this with plugins in the Esbuild and Rollup bundles which
* include this file.
*/
const MODULE_IMPORT_PREFIX = './';
export const loadModule = (
cmpMeta: d.ComponentRuntimeMeta,
hostRef: d.HostRef,
hmrVersionId?: string,
): Promise | d.ComponentConstructor | undefined => {
// loadModuleImport
const exportName = cmpMeta.$tagName$.replace(/-/g, '_');
const bundleId = cmpMeta.$lazyBundleId$;
if (BUILD.isDev && typeof bundleId !== 'string') {
consoleDevError(
`Trying to lazily load component <${cmpMeta.$tagName$}> with style mode "${hostRef.$modeName$}", but it does not exist.`,
);
return undefined;
} else if (!bundleId) {
return undefined;
}
const module = !BUILD.hotModuleReplacement ? cmpModules.get(bundleId) : false;
if (module) {
return module[exportName];
}
/*!__STENCIL_STATIC_IMPORT_SWITCH__*/
return import(
/* @vite-ignore */
/* webpackInclude: /\.entry\.js$/ */
/* webpackExclude: /\.system\.entry\.js$/ */
/* webpackMode: "lazy" */
`${MODULE_IMPORT_PREFIX}${bundleId}.entry.js${
BUILD.hotModuleReplacement && hmrVersionId ? '?s-hmr=' + hmrVersionId : ''
}`
).then(
(importedModule) => {
if (!BUILD.hotModuleReplacement) {
cmpModules.set(bundleId, importedModule);
}
return importedModule[exportName];
},
(e: Error) => {
consoleError(e, hostRef.$hostElement$);
},
);
};
================================================
FILE: src/client/client-log.ts
================================================
import { BUILD } from '@app-data';
import type * as d from '../declarations';
let customError: d.ErrorHandler;
export const consoleError: d.ErrorHandler = (e: any, el?: HTMLElement) => (customError || console.error)(e, el);
export const STENCIL_DEV_MODE = BUILD.isTesting
? ['STENCIL:'] // E2E testing
: [
'%cstencil',
'color: white;background:#4c47ff;font-weight: bold; font-size:10px; padding:2px 6px; border-radius: 5px',
];
export const consoleDevError = (...m: any[]) => console.error(...STENCIL_DEV_MODE, ...m);
export const consoleDevWarn = (...m: any[]) => console.warn(...STENCIL_DEV_MODE, ...m);
export const consoleDevInfo = (...m: any[]) => console.info(...STENCIL_DEV_MODE, ...m);
export const setErrorHandler = (handler: d.ErrorHandler) => (customError = handler);
================================================
FILE: src/client/client-patch-browser.ts
================================================
import { BUILD, NAMESPACE } from '@app-data';
import { consoleDevInfo, H, promiseResolve, win } from '@platform';
import type * as d from '../declarations';
export const patchBrowser = (): Promise => {
// NOTE!! This fn cannot use async/await!
if (BUILD.isDev && !BUILD.isTesting) {
consoleDevInfo('Running in development mode.');
}
if (BUILD.cloneNodeFix) {
// opted-in to polyfill cloneNode() for slot polyfilled components
patchCloneNodeFix((H as any).prototype);
}
const scriptElm = BUILD.scriptDataOpts
? win.document &&
Array.from(win.document.querySelectorAll('script')).find(
(s) =>
new RegExp(`\/${NAMESPACE}(\\.esm)?\\.js($|\\?|#)`).test(s.src) ||
s.getAttribute('data-stencil-namespace') === NAMESPACE,
)
: null;
const importMeta = import.meta.url;
const opts = BUILD.scriptDataOpts ? ((scriptElm as any) || {})['data-opts'] || {} : {};
if (importMeta !== '') {
opts.resourcesUrl = new URL('.', importMeta).href;
}
return promiseResolve(opts);
};
const patchCloneNodeFix = (HTMLElementPrototype: any) => {
const nativeCloneNodeFn = HTMLElementPrototype.cloneNode;
HTMLElementPrototype.cloneNode = function (this: Node, deep: boolean) {
if (this.nodeName === 'TEMPLATE') {
return nativeCloneNodeFn.call(this, deep);
}
const clonedNode = nativeCloneNodeFn.call(this, false);
const srcChildNodes = this.childNodes;
if (deep) {
for (let i = 0; i < srcChildNodes.length; i++) {
// Node.ATTRIBUTE_NODE === 2, and checking because IE11
if (srcChildNodes[i].nodeType !== 2) {
clonedNode.appendChild(srcChildNodes[i].cloneNode(true));
}
}
}
return clonedNode;
};
};
================================================
FILE: src/client/client-style.ts
================================================
import type * as d from '../declarations';
export const styles: d.StyleMap = /*@__PURE__*/ new Map();
export const modeResolutionChain: d.ResolutionHandler[] = [];
export const setScopedSSR = (_opts: d.HydrateFactoryOptions) => {};
export const needsScopedSSR = () => false;
================================================
FILE: src/client/client-task-queue.ts
================================================
import { BUILD } from '@app-data';
import type * as d from '../declarations';
import { PLATFORM_FLAGS } from '../runtime/runtime-constants';
import { consoleError } from './client-log';
import { plt, promiseResolve } from './client-window';
let queueCongestion = 0;
let queuePending = false;
const queueDomReads: d.RafCallback[] = [];
const queueDomWrites: d.RafCallback[] = [];
const queueDomWritesLow: d.RafCallback[] = [];
const queueTask = (queue: d.RafCallback[], write: boolean) => (cb: d.RafCallback) => {
queue.push(cb);
if (!queuePending) {
queuePending = true;
if (write && plt.$flags$ & PLATFORM_FLAGS.queueSync) {
nextTick(flush);
} else {
plt.raf(flush);
}
}
};
const consume = (queue: d.RafCallback[]) => {
for (let i = 0; i < queue.length; i++) {
try {
queue[i](performance.now());
} catch (e) {
consoleError(e);
}
}
queue.length = 0;
};
const consumeTimeout = (queue: d.RafCallback[], timeout: number) => {
let i = 0;
let ts = 0;
while (i < queue.length && (ts = performance.now()) < timeout) {
try {
queue[i++](ts);
} catch (e) {
consoleError(e);
}
}
if (i === queue.length) {
queue.length = 0;
} else if (i !== 0) {
queue.splice(0, i);
}
};
const flush = () => {
if (BUILD.asyncQueue) {
queueCongestion++;
}
// always force a bunch of medium callbacks to run, but still have
// a throttle on how many can run in a certain time
// DOM READS!!!
consume(queueDomReads);
// DOM WRITES!!!
if (BUILD.asyncQueue) {
const timeout =
(plt.$flags$ & PLATFORM_FLAGS.queueMask) === PLATFORM_FLAGS.appLoaded
? performance.now() + 14 * Math.ceil(queueCongestion * (1.0 / 10.0))
: Infinity;
consumeTimeout(queueDomWrites, timeout);
consumeTimeout(queueDomWritesLow, timeout);
if (queueDomWrites.length > 0) {
queueDomWritesLow.push(...queueDomWrites);
queueDomWrites.length = 0;
}
if ((queuePending = queueDomReads.length + queueDomWrites.length + queueDomWritesLow.length > 0)) {
// still more to do yet, but we've run out of time
// let's let this thing cool off and try again in the next tick
plt.raf(flush);
} else {
queueCongestion = 0;
}
} else {
consume(queueDomWrites);
if ((queuePending = queueDomReads.length > 0)) {
// still more to do yet, but we've run out of time
// let's let this thing cool off and try again in the next tick
plt.raf(flush);
}
}
};
export const nextTick = (cb: () => void) => promiseResolve().then(cb);
export const readTask = /*@__PURE__*/ queueTask(queueDomReads, false);
export const writeTask = /*@__PURE__*/ queueTask(queueDomWrites, true);
================================================
FILE: src/client/client-window.ts
================================================
import { BUILD } from '@app-data';
import type * as d from '../declarations';
interface StencilWindow extends Omit {
document?: Document;
}
export const win = (typeof window !== 'undefined' ? window : ({} as StencilWindow)) as StencilWindow;
export const H = ((win as any).HTMLElement || (class {} as any)) as HTMLElement;
export const plt: d.PlatformRuntime = {
$flags$: 0,
$resourcesUrl$: '',
jmp: (h) => h(),
raf: (h) => requestAnimationFrame(h),
ael: (el, eventName, listener, opts) => el.addEventListener(eventName, listener, opts),
rel: (el, eventName, listener, opts) => el.removeEventListener(eventName, listener, opts),
ce: (eventName, opts) => new CustomEvent(eventName, opts),
};
export const setPlatformHelpers = (helpers: {
jmp?: (c: any) => any;
raf?: (c: any) => number;
ael?: (el: any, eventName: string, listener: any, options: any) => void;
rel?: (el: any, eventName: string, listener: any, options: any) => void;
ce?: (eventName: string, opts?: any) => any;
}) => {
Object.assign(plt, helpers);
};
export const supportsShadow = BUILD.shadowDom;
export const supportsListenerOptions = /*@__PURE__*/ (() => {
let supportsListenerOptions = false;
try {
win.document?.addEventListener(
'e',
null,
Object.defineProperty({}, 'passive', {
get() {
supportsListenerOptions = true;
},
}),
);
} catch (e) {}
return supportsListenerOptions;
})();
export const promiseResolve = (v?: any) => Promise.resolve(v);
export const supportsConstructableStylesheets = BUILD.constructableCSS
? /*@__PURE__*/ (() => {
try {
if (!win.document.adoptedStyleSheets) {
return false;
}
new CSSStyleSheet();
return typeof new CSSStyleSheet().replaceSync === 'function';
} catch (e) {}
return false;
})()
: false;
// https://github.com/salesforce/lwc/blob/5af18fdd904bc6cfcf7b76f3c539490ff11515b2/packages/%40lwc/engine-dom/src/renderer.ts#L41-L43
export const supportsMutableAdoptedStyleSheets = supportsConstructableStylesheets
? /*@__PURE__*/ (() =>
!!win.document && Object.getOwnPropertyDescriptor(win.document.adoptedStyleSheets, 'length')!.writable)()
: false;
export { H as HTMLElement };
================================================
FILE: src/client/index.ts
================================================
export * from './client-build';
export * from './client-host-ref';
export * from './client-load-module';
export * from './client-log';
export * from './client-style';
export * from './client-task-queue';
export * from './client-window';
export { BUILD, Env, NAMESPACE } from '@app-data';
export * from '@runtime';
================================================
FILE: src/client/polyfills/core-js.js
================================================
/**
* core-js 3.6.5
* https://github.com/zloirock/core-js
* License: http://rock.mit-license.org
* © 2019 Denis Pushkarev (zloirock.ru)
*/
!function(t){"use strict";!function(t){var n={};function e(r){if(n[r])return n[r].exports;var o=n[r]={i:r,l:!1,exports:{}};return t[r].call(o.exports,o,o.exports,e),o.l=!0,o.exports}e.m=t,e.c=n,e.d=function(t,n,r){e.o(t,n)||Object.defineProperty(t,n,{enumerable:!0,get:r})},e.r=function(t){"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(t,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(t,"__esModule",{value:!0})},e.t=function(t,n){if(1&n&&(t=e(t)),8&n)return t;if(4&n&&"object"==typeof t&&t&&t.__esModule)return t;var r=Object.create(null);if(e.r(r),Object.defineProperty(r,"default",{enumerable:!0,value:t}),2&n&&"string"!=typeof t)for(var o in t)e.d(r,o,function(n){return t[n]}.bind(null,o));return r},e.n=function(t){var n=t&&t.__esModule?function(){return t.default}:function(){return t};return e.d(n,"a",n),n},e.o=function(t,n){return Object.prototype.hasOwnProperty.call(t,n)},e.p="",e(e.s=0)}([function(t,n,e){e(1),e(55),e(62),e(68),e(70),e(71),e(72),e(73),e(75),e(76),e(78),e(87),e(88),e(89),e(98),e(99),e(101),e(102),e(103),e(105),e(106),e(107),e(108),e(110),e(111),e(112),e(113),e(114),e(115),e(116),e(117),e(118),e(127),e(130),e(131),e(133),e(135),e(136),e(137),e(138),e(139),e(141),e(143),e(146),e(148),e(150),e(151),e(153),e(154),e(155),e(156),e(157),e(159),e(160),e(162),e(163),e(164),e(165),e(166),e(167),e(168),e(169),e(170),e(172),e(173),e(183),e(184),e(185),e(189),e(191),e(192),e(193),e(194),e(195),e(196),e(198),e(201),e(202),e(203),e(204),e(208),e(209),e(212),e(213),e(214),e(215),e(216),e(217),e(218),e(219),e(221),e(222),e(223),e(226),e(227),e(228),e(229),e(230),e(231),e(232),e(233),e(234),e(235),e(236),e(237),e(238),e(240),e(241),e(243),e(248),t.exports=e(246)},function(t,n,e){var r=e(2),o=e(6),i=e(45),a=e(14),u=e(46),c=e(39),f=e(47),s=e(48),l=e(52),p=e(49),h=e(53),v=p("isConcatSpreadable"),g=h>=51||!o((function(){var t=[];return t[v]=!1,t.concat()[0]!==t})),d=l("concat"),y=function(t){if(!a(t))return!1;var n=t[v];return void 0!==n?!!n:i(t)};r({target:"Array",proto:!0,forced:!g||!d},{concat:function(t){var n,e,r,o,i,a=u(this),l=s(a,0),p=0;for(n=-1,r=arguments.length;n9007199254740991)throw TypeError("Maximum allowed index exceeded");for(e=0;e=9007199254740991)throw TypeError("Maximum allowed index exceeded");f(l,p++,i)}return l.length=p,l}})},function(t,n,e){var r=e(3),o=e(4).f,i=e(18),a=e(21),u=e(22),c=e(32),f=e(44);t.exports=function(t,n){var e,s,l,p,h,v=t.target,g=t.global,d=t.stat;if(e=g?r:d?r[v]||u(v,{}):(r[v]||{}).prototype)for(s in n){if(p=n[s],l=t.noTargetGet?(h=o(e,s))&&h.value:e[s],!f(g?s:v+(d?".":"#")+s,t.forced)&&void 0!==l){if(typeof p==typeof l)continue;c(p,l)}(t.sham||l&&l.sham)&&i(p,"sham",!0),a(e,s,p,t)}}},function(t,n){var e=function(t){return t&&t.Math==Math&&t};t.exports=e("object"==typeof globalThis&&globalThis)||e("object"==typeof window&&window)||e("object"==typeof self&&self)||e("object"==typeof global&&global)||Function("return this")()},function(t,n,e){var r=e(5),o=e(7),i=e(8),a=e(9),u=e(13),c=e(15),f=e(16),s=Object.getOwnPropertyDescriptor;n.f=r?s:function(t,n){if(t=a(t),n=u(n,!0),f)try{return s(t,n)}catch(t){}if(c(t,n))return i(!o.f.call(t,n),t[n])}},function(t,n,e){var r=e(6);t.exports=!r((function(){return 7!=Object.defineProperty({},1,{get:function(){return 7}})[1]}))},function(t,n){t.exports=function(t){try{return!!t()}catch(t){return!0}}},function(t,n,e){var r={}.propertyIsEnumerable,o=Object.getOwnPropertyDescriptor,i=o&&!r.call({1:2},1);n.f=i?function(t){var n=o(this,t);return!!n&&n.enumerable}:r},function(t,n){t.exports=function(t,n){return{enumerable:!(1&t),configurable:!(2&t),writable:!(4&t),value:n}}},function(t,n,e){var r=e(10),o=e(12);t.exports=function(t){return r(o(t))}},function(t,n,e){var r=e(6),o=e(11),i="".split;t.exports=r((function(){return!Object("z").propertyIsEnumerable(0)}))?function(t){return"String"==o(t)?i.call(t,""):Object(t)}:Object},function(t,n){var e={}.toString;t.exports=function(t){return e.call(t).slice(8,-1)}},function(t,n){t.exports=function(t){if(null==t)throw TypeError("Can't call method on "+t);return t}},function(t,n,e){var r=e(14);t.exports=function(t,n){if(!r(t))return t;var e,o;if(n&&"function"==typeof(e=t.toString)&&!r(o=e.call(t)))return o;if("function"==typeof(e=t.valueOf)&&!r(o=e.call(t)))return o;if(!n&&"function"==typeof(e=t.toString)&&!r(o=e.call(t)))return o;throw TypeError("Can't convert object to primitive value")}},function(t,n){t.exports=function(t){return"object"==typeof t?null!==t:"function"==typeof t}},function(t,n){var e={}.hasOwnProperty;t.exports=function(t,n){return e.call(t,n)}},function(t,n,e){var r=e(5),o=e(6),i=e(17);t.exports=!r&&!o((function(){return 7!=Object.defineProperty(i("div"),"a",{get:function(){return 7}}).a}))},function(t,n,e){var r=e(3),o=e(14),i=r.document,a=o(i)&&o(i.createElement);t.exports=function(t){return a?i.createElement(t):{}}},function(t,n,e){var r=e(5),o=e(19),i=e(8);t.exports=r?function(t,n,e){return o.f(t,n,i(1,e))}:function(t,n,e){return t[n]=e,t}},function(t,n,e){var r=e(5),o=e(16),i=e(20),a=e(13),u=Object.defineProperty;n.f=r?u:function(t,n,e){if(i(t),n=a(n,!0),i(e),o)try{return u(t,n,e)}catch(t){}if("get"in e||"set"in e)throw TypeError("Accessors not supported");return"value"in e&&(t[n]=e.value),t}},function(t,n,e){var r=e(14);t.exports=function(t){if(!r(t))throw TypeError(String(t)+" is not an object");return t}},function(t,n,e){var r=e(3),o=e(18),i=e(15),a=e(22),u=e(23),c=e(25),f=c.get,s=c.enforce,l=String(String).split("String");(t.exports=function(t,n,e,u){var c=!!u&&!!u.unsafe,f=!!u&&!!u.enumerable,p=!!u&&!!u.noTargetGet;"function"==typeof e&&("string"!=typeof n||i(e,"name")||o(e,"name",n),s(e).source=l.join("string"==typeof n?n:"")),t!==r?(c?!p&&t[n]&&(f=!0):delete t[n],f?t[n]=e:o(t,n,e)):f?t[n]=e:a(n,e)})(Function.prototype,"toString",(function(){return"function"==typeof this&&f(this).source||u(this)}))},function(t,n,e){var r=e(3),o=e(18);t.exports=function(t,n){try{o(r,t,n)}catch(e){r[t]=n}return n}},function(t,n,e){var r=e(24),o=Function.toString;"function"!=typeof r.inspectSource&&(r.inspectSource=function(t){return o.call(t)}),t.exports=r.inspectSource},function(t,n,e){var r=e(3),o=e(22),i=r["__core-js_shared__"]||o("__core-js_shared__",{});t.exports=i},function(t,n,e){var r,o,i,a=e(26),u=e(3),c=e(14),f=e(18),s=e(15),l=e(27),p=e(31),h=u.WeakMap;if(a){var v=new h,g=v.get,d=v.has,y=v.set;r=function(t,n){return y.call(v,t,n),n},o=function(t){return g.call(v,t)||{}},i=function(t){return d.call(v,t)}}else{var x=l("state");p[x]=!0,r=function(t,n){return f(t,x,n),n},o=function(t){return s(t,x)?t[x]:{}},i=function(t){return s(t,x)}}t.exports={set:r,get:o,has:i,enforce:function(t){return i(t)?o(t):r(t,{})},getterFor:function(t){return function(n){var e;if(!c(n)||(e=o(n)).type!==t)throw TypeError("Incompatible receiver, "+t+" required");return e}}}},function(t,n,e){var r=e(3),o=e(23),i=r.WeakMap;t.exports="function"==typeof i&&/native code/.test(o(i))},function(t,n,e){var r=e(28),o=e(30),i=r("keys");t.exports=function(t){return i[t]||(i[t]=o(t))}},function(t,n,e){var r=e(29),o=e(24);(t.exports=function(t,n){return o[t]||(o[t]=void 0!==n?n:{})})("versions",[]).push({version:"3.6.5",mode:r?"pure":"global",copyright:"© 2020 Denis Pushkarev (zloirock.ru)"})},function(t,n){t.exports=!1},function(t,n){var e=0,r=Math.random();t.exports=function(t){return"Symbol("+String(void 0===t?"":t)+")_"+(++e+r).toString(36)}},function(t,n){t.exports={}},function(t,n,e){var r=e(15),o=e(33),i=e(4),a=e(19);t.exports=function(t,n){for(var e=o(n),u=a.f,c=i.f,f=0;fc;)r(u,e=n[c++])&&(~i(f,e)||f.push(e));return f}},function(t,n,e){var r=e(9),o=e(39),i=e(41),a=function(t){return function(n,e,a){var u,c=r(n),f=o(c.length),s=i(a,f);if(t&&e!=e){for(;f>s;)if((u=c[s++])!=u)return!0}else for(;f>s;s++)if((t||s in c)&&c[s]===e)return t||s||0;return!t&&-1}};t.exports={includes:a(!0),indexOf:a(!1)}},function(t,n,e){var r=e(40),o=Math.min;t.exports=function(t){return t>0?o(r(t),9007199254740991):0}},function(t,n){var e=Math.ceil,r=Math.floor;t.exports=function(t){return isNaN(t=+t)?0:(t>0?r:e)(t)}},function(t,n,e){var r=e(40),o=Math.max,i=Math.min;t.exports=function(t,n){var e=r(t);return e<0?o(e+n,0):i(e,n)}},function(t,n){t.exports=["constructor","hasOwnProperty","isPrototypeOf","propertyIsEnumerable","toLocaleString","toString","valueOf"]},function(t,n){n.f=Object.getOwnPropertySymbols},function(t,n,e){var r=e(6),o=/#|\.prototype\./,i=function(t,n){var e=u[a(t)];return e==f||e!=c&&("function"==typeof n?r(n):!!n)},a=i.normalize=function(t){return String(t).replace(o,".").toLowerCase()},u=i.data={},c=i.NATIVE="N",f=i.POLYFILL="P";t.exports=i},function(t,n,e){var r=e(11);t.exports=Array.isArray||function(t){return"Array"==r(t)}},function(t,n,e){var r=e(12);t.exports=function(t){return Object(r(t))}},function(t,n,e){var r=e(13),o=e(19),i=e(8);t.exports=function(t,n,e){var a=r(n);a in t?o.f(t,a,i(0,e)):t[a]=e}},function(t,n,e){var r=e(14),o=e(45),i=e(49)("species");t.exports=function(t,n){var e;return o(t)&&("function"!=typeof(e=t.constructor)||e!==Array&&!o(e.prototype)?r(e)&&null===(e=e[i])&&(e=void 0):e=void 0),new(void 0===e?Array:e)(0===n?0:n)}},function(t,n,e){var r=e(3),o=e(28),i=e(15),a=e(30),u=e(50),c=e(51),f=o("wks"),s=r.Symbol,l=c?s:s&&s.withoutSetter||a;t.exports=function(t){return i(f,t)||(u&&i(s,t)?f[t]=s[t]:f[t]=l("Symbol."+t)),f[t]}},function(t,n,e){var r=e(6);t.exports=!!Object.getOwnPropertySymbols&&!r((function(){return!String(Symbol())}))},function(t,n,e){var r=e(50);t.exports=r&&!Symbol.sham&&"symbol"==typeof Symbol.iterator},function(t,n,e){var r=e(6),o=e(49),i=e(53),a=o("species");t.exports=function(t){return i>=51||!r((function(){var n=[];return(n.constructor={})[a]=function(){return{foo:1}},1!==n[t](Boolean).foo}))}},function(t,n,e){var r,o,i=e(3),a=e(54),u=i.process,c=u&&u.versions,f=c&&c.v8;f?o=(r=f.split("."))[0]+r[1]:a&&(!(r=a.match(/Edge\/(\d+)/))||r[1]>=74)&&(r=a.match(/Chrome\/(\d+)/))&&(o=r[1]),t.exports=o&&+o},function(t,n,e){var r=e(34);t.exports=r("navigator","userAgent")||""},function(t,n,e){var r=e(2),o=e(56),i=e(57);r({target:"Array",proto:!0},{copyWithin:o}),i("copyWithin")},function(t,n,e){var r=e(46),o=e(41),i=e(39),a=Math.min;t.exports=[].copyWithin||function(t,n){var e=r(this),u=i(e.length),c=o(t,u),f=o(n,u),s=arguments.length>2?arguments[2]:void 0,l=a((void 0===s?u:o(s,u))-f,u-c),p=1;for(f0;)f in e?e[c]=e[f]:delete e[c],c+=p,f+=p;return e}},function(t,n,e){var r=e(49),o=e(58),i=e(19),a=r("unscopables"),u=Array.prototype;null==u[a]&&i.f(u,a,{configurable:!0,value:o(null)}),t.exports=function(t){u[a][t]=!0}},function(t,n,e){var r,o=e(20),i=e(59),a=e(42),u=e(31),c=e(61),f=e(17),s=e(27),l=s("IE_PROTO"),p=function(){},h=function(t){return"
`)}
AFTER:
The index.html should now include two scripts using the modern ES Module script pattern.
Note that only one file will actually be requested and loaded based on the browser's native support for ES Modules.
For more info, please see Using JavaScript modules on the web .
${escapeHtml(`type="module" src="/build/${
config.fsNamespace
}.esm .js"${escapeHtml(`>`)}
${escapeHtml(`nomodule ${escapeHtml(
`src="/build/${config.fsNamespace}.js">`,
)}
`;
return `${generatePreamble(config)}
(function() {
function checkSupport() {
if (!document.body) {
setTimeout(checkSupport);
return;
}
function supportsDynamicImports() {
try {
new Function('import("")');
return true;
} catch (e) {}
return false;
}
var supportsEsModules = !!('noModule' in document.createElement('script'));
if (!supportsEsModules) {
document.body.innerHTML = '${inlineHTML(htmlLegacy)}';
document.getElementById('current-browser-output').textContent = window.navigator.userAgent;
document.getElementById('es-modules-test').textContent = supportsEsModules;
document.getElementById('es-dynamic-modules-test').textContent = supportsDynamicImports();
document.getElementById('shadow-dom-test').textContent = !!(document.head.attachShadow);
document.getElementById('custom-elements-test').textContent = !!(window.customElements);
document.getElementById('css-variables-test').textContent = !!(window.CSS && window.CSS.supports && window.CSS.supports('color', 'var(--c)'));
document.getElementById('fetch-test').textContent = !!(window.fetch);
} else {
document.body.innerHTML = '${inlineHTML(htmlUpdate)}';
}
}
setTimeout(checkSupport);
})();`;
};
const inlineHTML = (html: string) => {
return html.replace(/\n/g, '\\n').replace(/\'/g, `\\'`).trim();
};
================================================
FILE: src/compiler/app-core/app-polyfills.ts
================================================
import { join } from '@utils';
import type * as d from '../../declarations';
export const getClientPolyfill = async (
config: d.ValidatedConfig,
compilerCtx: d.CompilerCtx,
polyfillFile: string,
) => {
const polyfillFilePath = join(
config.sys.getCompilerExecutingPath(),
'..',
'..',
'internal',
'client',
'polyfills',
polyfillFile,
);
return compilerCtx.fs.readFile(polyfillFilePath);
};
export const getAppBrowserCorePolyfills = async (config: d.ValidatedConfig, compilerCtx: d.CompilerCtx) => {
// read all the polyfill content, in this particular order
const polyfills = INLINE_POLYFILLS.slice();
const results = await Promise.all(
polyfills.map((polyfillFile) => getClientPolyfill(config, compilerCtx, polyfillFile)),
);
// concat the polyfills
return results.join('\n').trim();
};
// order of the polyfills matters!! test test test
// actual source of the polyfills are found in /src/client/polyfills/
const INLINE_POLYFILLS = ['core-js.js', 'dom.js', 'es5-html-element.js', 'system.js'];
================================================
FILE: src/compiler/app-core/bundle-app-core.ts
================================================
import type { OutputAsset, OutputChunk, OutputOptions, RollupBuild } from 'rollup';
import type * as d from '../../declarations';
import { STENCIL_CORE_ID } from '../bundle/entry-alias-ids';
/**
* Generate rollup output based on a rollup build and a series of options.
*
* @param build a rollup build
* @param options output options for rollup
* @param config a user-supplied configuration object
* @param entryModules a list of entry modules, for checking which chunks
* contain components
* @returns a Promise wrapping either build results or `null`
*/
export const generateRollupOutput = async (
build: RollupBuild,
options: OutputOptions,
config: d.ValidatedConfig,
entryModules: d.EntryModule[],
): Promise => {
if (build == null) {
return null;
}
const { output }: { output: [OutputChunk, ...(OutputChunk | OutputAsset)[]] } = await build.generate(options);
return output.map((chunk: OutputChunk | OutputAsset) => {
if (chunk.type === 'chunk') {
const isCore = Object.keys(chunk.modules).some((m) => m.includes(STENCIL_CORE_ID));
return {
type: 'chunk',
fileName: chunk.fileName,
map: chunk.map
? {
...chunk.map,
sourcesContent: chunk.map.sourcesContent || [],
}
: undefined,
code: chunk.code,
moduleFormat: options.format,
entryKey: chunk.name,
imports: chunk.imports,
isEntry: !!chunk.isEntry,
isComponent: !!chunk.isEntry && entryModules.some((m) => m.entryKey === chunk.name),
isBrowserLoader: chunk.isEntry && chunk.name === config.fsNamespace,
isIndex: chunk.isEntry && chunk.name === 'index',
isCore,
};
} else {
return {
type: 'asset',
fileName: chunk.fileName,
content: chunk.source as any,
};
}
});
};
================================================
FILE: src/compiler/build/build-ctx.ts
================================================
import { hasError, hasWarning, result } from '@utils';
import type * as d from '../../declarations';
import { validateConfig } from '../config/validate-config';
/**
* A new BuildCtx object is created for every build
* and rebuild.
*/
export class BuildContext implements d.BuildCtx {
buildId = -1;
buildMessages: string[] = [];
buildResults: d.CompilerBuildResults = null;
bundleBuildCount = 0;
collections: d.CollectionCompilerMeta[] = [];
completedTasks: d.BuildTask[] = [];
compilerCtx: d.CompilerCtx;
components: d.ComponentCompilerMeta[] = [];
componentGraph = new Map();
config: d.ValidatedConfig;
data: any = {};
buildStats?: result.Result = undefined;
esmBrowserComponentBundle: d.BundleModule[];
esmComponentBundle: d.BundleModule[];
es5ComponentBundle: d.BundleModule[];
systemComponentBundle: d.BundleModule[];
commonJsComponentBundle: d.BundleModule[];
diagnostics: d.Diagnostic[] = [];
dirsAdded: string[] = [];
dirsDeleted: string[] = [];
entryModules: d.EntryModule[] = [];
filesAdded: string[] = [];
filesChanged: string[] = [];
filesDeleted: string[] = [];
filesUpdated: string[] = [];
filesWritten: string[] = [];
globalStyle: string = undefined;
hasConfigChanges = false;
hasFinished = false;
hasHtmlChanges = false;
hasPrintedResults = false;
hasServiceWorkerChanges = false;
hasScriptChanges = true;
hasStyleChanges = true;
hydrateAppFilePath: string = null;
indexBuildCount = 0;
indexDoc: Document = undefined;
isRebuild = false;
moduleFiles: d.Module[] = [];
outputs: d.BuildOutput[] = [];
packageJson: d.PackageJsonData = {};
packageJsonFilePath: string = null;
pendingCopyTasks: Promise[] = [];
requiresFullBuild = true;
scriptsAdded: string[] = [];
scriptsDeleted: string[] = [];
startTime = Date.now();
styleBuildCount = 0;
stylesPromise: Promise = null;
stylesUpdated: d.BuildStyleUpdate[] = [];
timeSpan: d.LoggerTimeSpan = null;
timestamp: string;
transpileBuildCount = 0;
validateTypesPromise: Promise;
constructor(config: d.Config, compilerCtx: d.CompilerCtx) {
this.config = validateConfig(config, {}).config;
this.compilerCtx = compilerCtx;
this.buildId = ++this.compilerCtx.activeBuildId;
this.debug = config.logger.debug.bind(config.logger);
}
start() {
// get the build id from the incremented activeBuildId
// print out a good message
const msg = `${this.isRebuild ? 'rebuild' : 'build'}, ${this.config.fsNamespace}, ${
this.config.devMode ? 'dev' : 'prod'
} mode, started`;
const buildLog: d.BuildLog = {
buildId: this.buildId,
messages: [],
progress: 0,
};
this.compilerCtx.events.emit('buildLog', buildLog);
// create a timespan for this build
this.timeSpan = this.createTimeSpan(msg);
// create a build timestamp for this build
this.timestamp = getBuildTimestamp();
// debug log our new build
this.debug(`start build, ${this.timestamp}`);
const buildStart: d.CompilerBuildStart = {
buildId: this.buildId,
timestamp: this.timestamp,
};
this.compilerCtx.events.emit('buildStart', buildStart);
}
createTimeSpan(msg: string, debug?: boolean) {
if (!this.hasFinished || debug) {
if (debug) {
if (this.config.watch) {
msg = `${this.config.logger.cyan('[' + this.buildId + ']')} ${msg}`;
}
}
const timeSpan = this.config.logger.createTimeSpan(msg, debug, this.buildMessages);
if (!debug && this.compilerCtx.events) {
const buildLog: d.BuildLog = {
buildId: this.buildId,
messages: this.buildMessages,
progress: getProgress(this.completedTasks),
};
this.compilerCtx.events.emit('buildLog', buildLog);
}
return {
duration: () => {
return timeSpan.duration();
},
finish: (finishedMsg: string, color?: string, bold?: boolean, newLineSuffix?: boolean) => {
if (!this.hasFinished || debug) {
if (debug) {
if (this.config.watch) {
finishedMsg = `${this.config.logger.cyan('[' + this.buildId + ']')} ${finishedMsg}`;
}
}
timeSpan.finish(finishedMsg, color, bold, newLineSuffix);
if (!debug) {
const buildLog: d.BuildLog = {
buildId: this.buildId,
messages: this.buildMessages.slice(),
progress: getProgress(this.completedTasks),
};
this.compilerCtx.events.emit('buildLog', buildLog);
}
}
return timeSpan.duration();
},
};
}
return {
duration() {
return 0;
},
finish() {
return 0;
},
};
}
debug(msg: string) {
this.config.logger.debug(msg);
}
get hasError() {
return hasError(this.diagnostics);
}
get hasWarning() {
return hasWarning(this.diagnostics);
}
progress(t: d.BuildTask) {
this.completedTasks.push(t);
}
async validateTypesBuild() {
if (this.hasError) {
// no need to wait on this one since
// we already aborted this build
return;
}
if (!this.validateTypesPromise) {
// there is no pending validate types promise
// so it probably already finished
// so no need to wait on anything
return;
}
if (!this.config.watch) {
// this is not a watch build, so we need to make
// sure that the type validation has finished
this.debug(`build, non-watch, waiting on validateTypes`);
await this.validateTypesPromise;
this.debug(`build, non-watch, finished waiting on validateTypes`);
}
}
}
/**
* Generate a timestamp of the format `YYYY-MM-DDThh:mm:ss`, using the number of seconds that have elapsed since
* January 01, 1970, and the time this function was called
* @returns the generated timestamp
*/
export const getBuildTimestamp = () => {
const d = new Date();
// YYYY-MM-DDThh:mm:ss
let timestamp = d.getUTCFullYear() + '-';
timestamp += ('0' + (d.getUTCMonth() + 1)).slice(-2) + '-';
timestamp += ('0' + d.getUTCDate()).slice(-2) + 'T';
timestamp += ('0' + d.getUTCHours()).slice(-2) + ':';
timestamp += ('0' + d.getUTCMinutes()).slice(-2) + ':';
timestamp += ('0' + d.getUTCSeconds()).slice(-2);
return timestamp;
};
const getProgress = (completedTasks: d.BuildTask[]) => {
let progressIndex = 0;
const taskKeys = Object.keys(ProgressTask);
taskKeys.forEach((taskKey, index) => {
if (completedTasks.includes((ProgressTask as any)[taskKey])) {
progressIndex = index;
}
});
return (progressIndex + 1) / taskKeys.length;
};
export const ProgressTask = {
emptyOutputTargets: {},
transpileApp: {},
generateStyles: {},
generateOutputTargets: {},
validateTypesBuild: {},
writeBuildFiles: {},
};
================================================
FILE: src/compiler/build/build-finish.ts
================================================
import { isFunction, isRemoteUrl, relative } from '@utils';
import type * as d from '../../declarations';
import { generateBuildResults } from './build-results';
import { generateBuildStats, writeBuildStats } from './build-stats';
/**
* Finish a build as having completed successfully
* @param buildCtx the build context for the build being aborted
* @returns the build results
*/
export const buildFinish = async (buildCtx: d.BuildCtx): Promise => {
const results = await buildDone(buildCtx.config, buildCtx.compilerCtx, buildCtx, false);
const buildLog: d.BuildLog = {
buildId: buildCtx.buildId,
messages: buildCtx.buildMessages.slice(),
progress: 1,
};
buildCtx.compilerCtx.events.emit('buildLog', buildLog);
return results;
};
/**
* Finish a build early due to failure. During the build process, a fatal error has occurred where the compiler cannot
* continue further
* @param buildCtx the build context for the build being aborted
* @returns the build results
*/
export const buildAbort = (buildCtx: d.BuildCtx): Promise => {
return buildDone(buildCtx.config, buildCtx.compilerCtx, buildCtx, true);
};
/**
* Mark a build as done
* @param config the Stencil configuration used for the build
* @param compilerCtx the compiler context associated with the build
* @param buildCtx the build context associated with the build to mark as done
* @param aborted true if the build ended early due to failure, false otherwise
* @returns the build results
*/
const buildDone = async (
config: d.ValidatedConfig,
compilerCtx: d.CompilerCtx,
buildCtx: d.BuildCtx,
aborted: boolean,
): Promise => {
if (buildCtx.hasFinished && buildCtx.buildResults) {
// we've already marked this build as finished and
// already created the build results, just return these
return buildCtx.buildResults;
}
// create the build results data
buildCtx.buildResults = generateBuildResults(config, compilerCtx, buildCtx);
// After the build results are available on the buildCtx, call the stats and set it.
// We will use this later to write the files.
buildCtx.buildStats = generateBuildStats(config, buildCtx);
await writeBuildStats(config, buildCtx.buildStats);
buildCtx.debug(`${aborted ? 'aborted' : 'finished'} build, ${buildCtx.buildResults.duration}ms`);
// log any errors/warnings
if (!buildCtx.hasFinished) {
// haven't set this build as finished yet
if (!buildCtx.hasPrintedResults) {
cleanDiagnosticsRelativePath(config, buildCtx.buildResults.diagnostics);
config.logger.printDiagnostics(buildCtx.buildResults.diagnostics);
}
const hasChanges = buildCtx.hasScriptChanges || buildCtx.hasStyleChanges;
if (buildCtx.isRebuild && hasChanges && buildCtx.buildResults.hmr && !aborted) {
// this is a rebuild, and we've got hmr data
// and this build hasn't been aborted
logHmr(config.logger, buildCtx.buildResults.hmr);
}
// create a nice pretty message stating what happened
const buildText = buildCtx.isRebuild ? 'rebuild' : 'build';
const watchText = config.watch ? ', watching for changes...' : '';
let buildStatus = 'finished';
let statusColor = 'green';
if (buildCtx.hasError) {
// gosh darn, build had errors
// ಥ_ಥ
buildStatus = 'failed';
statusColor = 'red';
} else {
// successful build!
// ┏(°.°)┛ ┗(°.°)┓ ┗(°.°)┛ ┏(°.°)┓
compilerCtx.changedFiles.clear();
compilerCtx.hasSuccessfulBuild = true;
buildCtx.buildResults.hasSuccessfulBuild = true;
}
// print out the time it took to build
// and add the duration to the build results
if (!buildCtx.hasPrintedResults) {
buildCtx.timeSpan.finish(`${buildText} ${buildStatus}${watchText}`, statusColor, true, true);
buildCtx.hasPrintedResults = true;
}
// emit a buildFinish event for anyone who cares
compilerCtx.events.emit('buildFinish', buildCtx.buildResults);
// write all of our logs to disk if config'd to do so
// do this even if there are errors or not the active build
if (isFunction(config.logger.writeLogs)) {
config.logger.writeLogs(buildCtx.isRebuild);
}
}
// it's official, this build has finished
buildCtx.hasFinished = true;
if (!config.watch) {
compilerCtx.reset();
if (global.gc) {
buildCtx.debug(`triggering forced gc`);
global.gc();
buildCtx.debug(`forced gc finished`);
}
}
return buildCtx.buildResults;
};
/**
* In a Hot Module Replacement (HMR) context, log what changed between builds
* @param logger the instance of the logger to report what's changed
* @param hmr the HMR data, which includes what's changed between builds
*/
const logHmr = (logger: d.Logger, hmr: d.HotModuleReplacement): void => {
if (hmr.componentsUpdated) {
cleanupUpdateMsg(logger, `updated component`, hmr.componentsUpdated);
}
if (hmr.inlineStylesUpdated) {
const inlineStyles = hmr.inlineStylesUpdated
.map((s) => s.styleTag)
.reduce((arr, v) => {
if (!arr.includes(v)) {
arr.push(v);
}
return arr;
}, [] as string[]);
cleanupUpdateMsg(logger, `updated style`, inlineStyles);
}
if (hmr.externalStylesUpdated) {
cleanupUpdateMsg(logger, `updated stylesheet`, hmr.externalStylesUpdated);
}
if (hmr.imagesUpdated) {
cleanupUpdateMsg(logger, `updated image`, hmr.imagesUpdated);
}
};
const cleanupUpdateMsg = (logger: d.Logger, msg: string, fileNames: string[]) => {
if (fileNames.length > 0) {
let fileMsg = '';
if (fileNames.length > 7) {
const remaining = fileNames.length - 6;
fileNames = fileNames.slice(0, 6);
fileMsg = fileNames.join(', ') + `, +${remaining} others`;
} else {
fileMsg = fileNames.join(', ');
}
if (fileNames.length > 1) {
msg += 's';
}
logger.info(`${msg}: ${logger.cyan(fileMsg)}`);
}
};
/**
* Update the relative file path for diagnostics. The updates are done in place.
* @param config the Stencil configuration associated with the current build
* @param diagnostics the diagnostics to update
*/
const cleanDiagnosticsRelativePath = (config: d.Config, diagnostics: ReadonlyArray): void => {
diagnostics.forEach((diagnostic) => {
if (!diagnostic.relFilePath && diagnostic.absFilePath && !isRemoteUrl(diagnostic.absFilePath) && config.rootDir) {
diagnostic.relFilePath = relative(config.rootDir, diagnostic.absFilePath);
}
});
};
================================================
FILE: src/compiler/build/build-hmr.ts
================================================
import { isGlob, isOutputTargetWww, normalizePath, sortBy } from '@utils';
import { minimatch } from 'minimatch';
import { basename } from 'path';
import type * as d from '../../declarations';
import { getScopeId } from '../style/scope-css';
export const generateHmr = (config: d.Config, compilerCtx: d.CompilerCtx, buildCtx: d.BuildCtx) => {
if (config.devServer?.reloadStrategy == null) {
return null;
}
const hmr: d.HotModuleReplacement = {
reloadStrategy: config.devServer.reloadStrategy,
versionId: Date.now().toString().substring(6) + '' + Math.round(Math.random() * 89999 + 10000),
};
if (buildCtx.scriptsAdded.length > 0) {
hmr.scriptsAdded = buildCtx.scriptsAdded.slice();
}
if (buildCtx.scriptsDeleted.length > 0) {
hmr.scriptsDeleted = buildCtx.scriptsDeleted.slice();
}
const excludeHmr = excludeHmrFiles(config, config.devServer.excludeHmr, buildCtx.filesChanged);
if (excludeHmr.length > 0) {
hmr.excludeHmr = excludeHmr.slice();
}
if (buildCtx.hasHtmlChanges) {
hmr.indexHtmlUpdated = true;
}
if (buildCtx.hasServiceWorkerChanges) {
hmr.serviceWorkerUpdated = true;
}
const outputTargetsWww = config.outputTargets.filter(isOutputTargetWww);
const componentsUpdated = getComponentsUpdated(compilerCtx, buildCtx);
if (componentsUpdated) {
hmr.componentsUpdated = componentsUpdated;
}
if (Object.keys(buildCtx.stylesUpdated).length > 0) {
hmr.inlineStylesUpdated = sortBy(
buildCtx.stylesUpdated.map((s) => {
return {
styleId: getScopeId(s.styleTag, s.styleMode),
styleTag: s.styleTag,
styleText: s.styleText,
} as d.HmrStyleUpdate;
}),
(s) => s.styleId,
);
}
const externalStylesUpdated = getExternalStylesUpdated(buildCtx, outputTargetsWww);
if (externalStylesUpdated) {
hmr.externalStylesUpdated = externalStylesUpdated;
}
const externalImagesUpdated = getImagesUpdated(buildCtx, outputTargetsWww);
if (externalImagesUpdated) {
hmr.imagesUpdated = externalImagesUpdated;
}
return hmr;
};
const getComponentsUpdated = (compilerCtx: d.CompilerCtx, buildCtx: d.BuildCtx) => {
// find all of the components that would be affected from the file changes
if (!buildCtx.filesChanged) {
return null;
}
const filesToLookForImporters = buildCtx.filesChanged.filter((f) => {
return f.endsWith('.ts') || f.endsWith('.tsx') || f.endsWith('.js') || f.endsWith('.jsx');
});
if (filesToLookForImporters.length === 0) {
return null;
}
const changedScriptFiles: string[] = [];
const checkedFiles = new Set();
const allModuleFiles = buildCtx.moduleFiles.filter((m) => m.localImports && m.localImports.length > 0);
while (filesToLookForImporters.length > 0) {
const scriptFile = filesToLookForImporters.shift();
addTsFileImporters(allModuleFiles, filesToLookForImporters, checkedFiles, changedScriptFiles, scriptFile);
}
const tags = changedScriptFiles.reduce((tags, changedTsFile) => {
const moduleFile = compilerCtx.moduleMap.get(changedTsFile);
if (moduleFile != null) {
moduleFile.cmps.forEach((cmp) => {
if (typeof cmp.tagName === 'string') {
if (!tags.includes(cmp.tagName)) {
tags.push(cmp.tagName);
}
}
});
}
return tags;
}, [] as string[]);
if (tags.length === 0) {
return null;
}
return tags.sort();
};
const addTsFileImporters = (
allModuleFiles: d.Module[],
filesToLookForImporters: string[],
checkedFiles: Set,
changedScriptFiles: string[],
scriptFile: string,
) => {
if (!changedScriptFiles.includes(scriptFile)) {
// add it to our list of files to transpile
changedScriptFiles.push(scriptFile);
}
if (checkedFiles.has(scriptFile)) {
// already checked this file
return;
}
checkedFiles.add(scriptFile);
// get all the ts files that import this ts file
const tsFilesThatImportsThisTsFile = allModuleFiles.reduce((arr, moduleFile) => {
moduleFile.localImports.forEach((localImport) => {
let checkFile = localImport;
if (checkFile === scriptFile) {
arr.push(moduleFile.sourceFilePath);
return;
}
checkFile = localImport + '.tsx';
if (checkFile === scriptFile) {
arr.push(moduleFile.sourceFilePath);
return;
}
checkFile = localImport + '.ts';
if (checkFile === scriptFile) {
arr.push(moduleFile.sourceFilePath);
return;
}
checkFile = localImport + '.js';
if (checkFile === scriptFile) {
arr.push(moduleFile.sourceFilePath);
return;
}
});
return arr;
}, [] as string[]);
// add all the files that import this ts file to the list of ts files we need to look through
tsFilesThatImportsThisTsFile.forEach((tsFileThatImportsThisTsFile) => {
// if we add to this array, then the while look will keep working until it's empty
filesToLookForImporters.push(tsFileThatImportsThisTsFile);
});
};
const getExternalStylesUpdated = (buildCtx: d.BuildCtx, outputTargetsWww: d.OutputTargetWww[]) => {
if (!buildCtx.isRebuild || outputTargetsWww.length === 0) {
return null;
}
const cssFiles = buildCtx.filesWritten.filter((f) => f.endsWith('.css'));
if (cssFiles.length === 0) {
return null;
}
return cssFiles.map((cssFile) => basename(cssFile)).sort();
};
const getImagesUpdated = (buildCtx: d.BuildCtx, outputTargetsWww: d.OutputTargetWww[]) => {
if (outputTargetsWww.length === 0) {
return null;
}
const imageFiles = buildCtx.filesChanged.reduce((arr, filePath) => {
if (IMAGE_EXT.some((ext) => filePath.toLowerCase().endsWith(ext))) {
const fileName = basename(filePath);
if (!arr.includes(fileName)) {
arr.push(fileName);
}
}
return arr;
}, []);
if (imageFiles.length === 0) {
return null;
}
return imageFiles.sort();
};
/**
* Determine a list of files (if any) which should be excluded from HMR updates.
*
* @param config a user-supplied config
* @param excludeHmr a list of glob patterns that should be used to determine
* whether to exclude a file or not (a file will be excluded if it matches one
* @param filesChanged an array of files which are changed in the HMR update
* currently under consideration
* @returns a sorted list of files to exclude
*/
const excludeHmrFiles = (config: d.Config, excludeHmr: string[], filesChanged: string[]): string[] => {
const excludeFiles: string[] = [];
if (!excludeHmr || excludeHmr.length === 0) {
return excludeFiles;
}
excludeHmr.forEach((excludeHmr) => {
return filesChanged
.map((fileChanged) => {
let shouldExclude = false;
if (isGlob(excludeHmr)) {
shouldExclude = minimatch(fileChanged, excludeHmr);
} else {
shouldExclude = normalizePath(excludeHmr) === normalizePath(fileChanged);
}
if (shouldExclude) {
config.logger.debug(`excludeHmr: ${fileChanged}`);
excludeFiles.push(basename(fileChanged));
}
return shouldExclude;
})
.some((r) => r);
});
return excludeFiles.sort();
};
const IMAGE_EXT = ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.svg'];
================================================
FILE: src/compiler/build/build-results.ts
================================================
import { fromEntries, hasError, isString, normalizeDiagnostics } from '@utils';
import type * as d from '../../declarations';
import { getBuildTimestamp } from './build-ctx';
import { generateHmr } from './build-hmr';
export const generateBuildResults = (config: d.Config, compilerCtx: d.CompilerCtx, buildCtx: d.BuildCtx) => {
const componentGraph = buildCtx.componentGraph ? fromEntries(buildCtx.componentGraph.entries()) : undefined;
const buildResults: d.CompilerBuildResults = {
buildId: buildCtx.buildId,
diagnostics: normalizeDiagnostics(compilerCtx, buildCtx.diagnostics),
dirsAdded: buildCtx.dirsAdded.slice().sort(),
dirsDeleted: buildCtx.dirsDeleted.slice().sort(),
duration: Date.now() - buildCtx.startTime,
filesAdded: buildCtx.filesAdded.slice().sort(),
filesChanged: buildCtx.filesChanged.slice().sort(),
filesDeleted: buildCtx.filesDeleted.slice().sort(),
filesUpdated: buildCtx.filesUpdated.slice().sort(),
hasError: hasError(buildCtx.diagnostics),
hasSuccessfulBuild: compilerCtx.hasSuccessfulBuild,
isRebuild: buildCtx.isRebuild,
namespace: config.namespace,
outputs: compilerCtx.fs.getBuildOutputs(),
rootDir: config.rootDir,
srcDir: config.srcDir,
timestamp: getBuildTimestamp(),
componentGraph,
};
const hmr = generateHmr(config, compilerCtx, buildCtx);
if (hmr != null) {
buildResults.hmr = hmr;
}
if (isString(buildCtx.hydrateAppFilePath)) {
buildResults.hydrateAppFilePath = buildCtx.hydrateAppFilePath;
}
compilerCtx.lastBuildResults = Object.assign({}, buildResults as any);
return buildResults;
};
================================================
FILE: src/compiler/build/build-stats.ts
================================================
import { byteSize, isOutputTargetStats, result, sortBy } from '@utils';
import type * as d from '../../declarations';
/**
* Generates the Build Stats from the buildCtx. Writes any files to the file system.
* @param config the project build configuration
* @param buildCtx An instance of the build which holds the details about the build
* @returns CompilerBuildStats or an Object including diagnostics.
*/
export function generateBuildStats(
config: d.ValidatedConfig,
buildCtx: d.BuildCtx,
): result.Result {
// TODO(STENCIL-461): Investigate making this return only a single type
const buildResults = buildCtx.buildResults;
try {
if (buildResults.hasError) {
return result.err({
diagnostics: buildResults.diagnostics,
});
} else {
const stats: d.CompilerBuildStats = {
timestamp: buildResults.timestamp,
compiler: {
name: config.sys.name,
version: config.sys.version,
},
app: {
namespace: config.namespace,
fsNamespace: config.fsNamespace,
components: Object.keys(buildResults.componentGraph ?? {}).length,
entries: Object.keys(buildResults.componentGraph ?? {}).length,
bundles: buildResults.outputs.reduce((total, en) => total + en.files.length, 0),
outputs: getAppOutputs(config, buildResults),
},
options: {
minifyJs: !!config.minifyJs,
minifyCss: !!config.minifyCss,
hashFileNames: !!config.hashFileNames,
hashedFileNameLength: config.hashedFileNameLength,
buildEs5: !!config.buildEs5,
},
formats: {
esmBrowser: sanitizeBundlesForStats(buildCtx.esmBrowserComponentBundle),
esm: sanitizeBundlesForStats(buildCtx.esmComponentBundle),
es5: sanitizeBundlesForStats(buildCtx.es5ComponentBundle),
system: sanitizeBundlesForStats(buildCtx.systemComponentBundle),
commonjs: sanitizeBundlesForStats(buildCtx.commonJsComponentBundle),
},
components: getComponentsFileMap(config, buildCtx),
entries: buildCtx.entryModules,
componentGraph: buildResults.componentGraph ?? {},
sourceGraph: getSourceGraph(config, buildCtx),
rollupResults: buildCtx.rollupResults ?? { modules: [] },
collections: getCollections(config, buildCtx),
};
return result.ok(stats);
}
} catch (e: unknown) {
const diagnostic: d.Diagnostic = {
level: `error`,
lines: [],
messageText: `Generate Build Stats Error: ` + e,
type: `build`,
};
return result.err({
diagnostics: [diagnostic],
});
}
}
/**
* Writes the files from the stats config to the file system
* @param config the project build configuration
* @param data the information to write out to disk (as specified by each stats output target specified in the provided
* config)
*/
export async function writeBuildStats(
config: d.ValidatedConfig,
data: result.Result,
): Promise {
const statsTargets = config.outputTargets.filter(isOutputTargetStats);
await result.map(data, async (compilerBuildStats) => {
await Promise.all(
statsTargets.map(async (outputTarget) => {
if (outputTarget.file) {
const result = await config.sys.writeFile(outputTarget.file, JSON.stringify(compilerBuildStats, null, 2));
if (result.error) {
config.logger.warn([`Stats failed to write file to ${outputTarget.file}`]);
}
}
}),
);
});
}
function sanitizeBundlesForStats(bundleArray: ReadonlyArray): ReadonlyArray {
if (!bundleArray) {
return [];
}
return bundleArray.map((bundle) => {
return {
key: bundle.entryKey,
components: bundle.cmps.map((c) => c.tagName),
bundleId: bundle.output.bundleId,
fileName: bundle.output.fileName,
imports: bundle.rollupResult.imports,
// code: bundle.rollupResult.code, // (use this to debug)
// Currently, this number is inaccurate vs what seems to be on disk.
originalByteSize: byteSize(bundle.rollupResult.code),
};
});
}
function getSourceGraph(config: d.ValidatedConfig, buildCtx: d.BuildCtx) {
const sourceGraph: d.BuildSourceGraph = {};
sortBy(buildCtx.moduleFiles, (m) => m.sourceFilePath).forEach((moduleFile) => {
const key = relativePath(config, moduleFile.sourceFilePath);
sourceGraph[key] = moduleFile.localImports.map((localImport) => relativePath(config, localImport)).sort();
});
return sourceGraph;
}
function getAppOutputs(config: d.ValidatedConfig, buildResults: d.CompilerBuildResults) {
return buildResults.outputs.map((output) => {
return {
name: output.type,
files: output.files.length,
generatedFiles: output.files.map((file) => relativePath(config, file)),
};
});
}
function getComponentsFileMap(config: d.ValidatedConfig, buildCtx: d.BuildCtx) {
return buildCtx.components.map((component) => {
return {
tag: component.tagName,
path: relativePath(config, component.jsFilePath),
source: relativePath(config, component.sourceFilePath),
elementRef: component.elementRef,
componentClassName: component.componentClassName,
assetsDirs: component.assetsDirs,
dependencies: component.dependencies,
dependents: component.dependents,
directDependencies: component.directDependencies,
directDependents: component.directDependents,
docs: component.docs,
encapsulation: component.encapsulation,
excludeFromCollection: component.excludeFromCollection,
events: component.events,
internal: component.internal,
listeners: component.listeners,
methods: component.methods,
potentialCmpRefs: component.potentialCmpRefs,
properties: component.properties,
shadowDelegatesFocus: component.shadowDelegatesFocus,
states: component.states,
};
});
}
function getCollections(config: d.ValidatedConfig, buildCtx: d.BuildCtx): d.CompilerBuildStatCollection[] {
return buildCtx.collections
.map((c) => {
return {
name: c.collectionName,
source: relativePath(config, c.moduleDir),
tags: c.moduleFiles.map((m) => m.cmps.map((cmp: d.ComponentCompilerMeta) => cmp.tagName)).sort(),
};
})
.sort((a, b) => {
if (a.name < b.name) return -1;
if (a.name > b.name) return 1;
return 0;
});
}
function relativePath(config: d.ValidatedConfig, file: string) {
return config.sys.normalizePath(config.sys.platformPath.relative(config.rootDir, file));
}
================================================
FILE: src/compiler/build/build.ts
================================================
import { createDocument } from '@stencil/core/mock-doc';
import { catchError, isString, readPackageJson } from '@utils';
import ts from 'typescript';
import type * as d from '../../declarations';
import { generateOutputTargets } from '../output-targets';
import { emptyOutputTargets } from '../output-targets/empty-dir';
import { generateGlobalStyles } from '../style/global-styles';
import { runTsProgram, validateTypesAfterGeneration } from '../transpile/run-program';
import { buildAbort, buildFinish } from './build-finish';
import { writeBuild } from './write-build';
export const build = async (
config: d.ValidatedConfig,
compilerCtx: d.CompilerCtx,
buildCtx: d.BuildCtx,
tsBuilder: ts.BuilderProgram,
) => {
try {
// reset process.cwd() for 3rd-party plugins
process.chdir(config.rootDir);
// empty the directories on the first build
await emptyOutputTargets(config, compilerCtx, buildCtx);
if (buildCtx.hasError) return buildAbort(buildCtx);
if (config.srcIndexHtml) {
const indexSrcHtml = await compilerCtx.fs.readFile(config.srcIndexHtml);
if (isString(indexSrcHtml)) {
buildCtx.indexDoc = createDocument(indexSrcHtml);
}
}
await readPackageJson(config, compilerCtx, buildCtx);
if (buildCtx.hasError) return buildAbort(buildCtx);
// run typescript program
const tsTimeSpan = buildCtx.createTimeSpan('transpile started');
const emittedDts = await runTsProgram(config, compilerCtx, buildCtx, tsBuilder);
tsTimeSpan.finish('transpile finished');
if (buildCtx.hasError) return buildAbort(buildCtx);
// generate types and validate AFTER components.d.ts is written
const { hasTypesChanged, needsRebuild } = await validateTypesAfterGeneration(
config,
compilerCtx,
buildCtx,
tsBuilder,
emittedDts,
);
if (buildCtx.hasError) return buildAbort(buildCtx);
if (needsRebuild || (config.watch && hasTypesChanged)) {
// Abort and signal that a rebuild is needed:
// - needsRebuild: components.d.ts was just generated, need fresh TS program
// - watch mode with types changed: let watch trigger rebuild
return null;
}
// preprocess and generate styles before any outputTarget starts
buildCtx.stylesPromise = generateGlobalStyles(config, compilerCtx, buildCtx);
if (buildCtx.hasError) return buildAbort(buildCtx);
// create outputs
await generateOutputTargets(config, compilerCtx, buildCtx);
if (buildCtx.hasError) return buildAbort(buildCtx);
// write outputs
await buildCtx.stylesPromise;
await writeBuild(config, compilerCtx, buildCtx);
} catch (e: any) {
// ¯\_(ツ)_/¯
catchError(buildCtx.diagnostics, e);
}
// TODO
// clear changed files
compilerCtx.changedFiles.clear();
// return what we've learned today
return buildFinish(buildCtx);
};
================================================
FILE: src/compiler/build/compiler-ctx.ts
================================================
import { join, noop, normalizePath } from '@utils';
import { basename, dirname, extname } from 'path';
import type * as d from '../../declarations';
import { buildEvents } from '../events';
import { InMemoryFileSystem } from '../sys/in-memory-fs';
/**
* The CompilerCtx is a persistent object that's reused throughout
* all builds and rebuilds. The data within this object is used
* for in-memory caching, and can be reset, but the object itself
* is always the same.
*/
export class CompilerContext implements d.CompilerCtx {
version = 2;
activeBuildId = -1;
activeFilesAdded: string[] = [];
activeFilesDeleted: string[] = [];
activeFilesUpdated: string[] = [];
activeDirsAdded: string[] = [];
activeDirsDeleted: string[] = [];
addWatchDir: (path: string) => void = noop;
addWatchFile: (path: string) => void = noop;
cache: d.Cache;
cssModuleImports = new Map();
changedFiles = new Set();
changedModules = new Set();
collections: d.CollectionCompilerMeta[] = [];
compilerOptions: any = null;
events = buildEvents();
fs: InMemoryFileSystem;
hasSuccessfulBuild = false;
isActivelyBuilding = false;
lastBuildResults: d.CompilerBuildResults = null;
moduleMap: d.ModuleMap = new Map();
nodeMap = new WeakMap();
resolvedCollections = new Set();
rollupCache = new Map();
rollupCacheHydrate: any = null;
rollupCacheLazy: any = null;
rollupCacheNative: any = null;
cachedGlobalStyle: string;
styleModeNames = new Set();
worker: d.CompilerWorkerContext = null;
reset() {
this.cache.clear();
this.cssModuleImports.clear();
this.cachedGlobalStyle = null;
this.collections.length = 0;
this.compilerOptions = null;
this.hasSuccessfulBuild = false;
this.rollupCacheHydrate = null;
this.rollupCacheLazy = null;
this.rollupCacheNative = null;
this.moduleMap.clear();
this.resolvedCollections.clear();
if (this.fs != null) {
this.fs.clearCache();
}
}
}
/**
* Get a {@link d.Module} from the current compiler context which corresponds
* to a supplied source file path. If a module record corresponding to the
* supplied path is not yet allocated, create one, save it in the compiler
* context, and then return the module record.
*
* @param compilerCtx the current compiler context
* @param sourceFilePath the path for which we want a module record
* @returns a module record corresponding to the supplied source file path
*/
export const getModuleLegacy = (compilerCtx: d.CompilerCtx, sourceFilePath: string): d.Module => {
sourceFilePath = normalizePath(sourceFilePath);
const moduleFile = compilerCtx.moduleMap.get(sourceFilePath);
if (moduleFile != null) {
return moduleFile;
} else {
const sourceFileDir = dirname(sourceFilePath);
const sourceFileExt = extname(sourceFilePath);
const sourceFileName = basename(sourceFilePath, sourceFileExt);
const jsFilePath = join(sourceFileDir, sourceFileName + '.js');
const moduleFile: d.Module = {
sourceFilePath: sourceFilePath,
jsFilePath: jsFilePath,
cmps: [],
isExtended: false,
isMixin: false,
hasExportableMixins: false,
coreRuntimeApis: [],
outputTargetCoreRuntimeApis: {},
collectionName: null,
dtsFilePath: null,
excludeFromCollection: false,
externalImports: [],
hasVdomAttribute: false,
hasVdomXlink: false,
hasVdomClass: false,
hasVdomFunctional: false,
hasVdomKey: false,
hasVdomListener: false,
hasVdomPropOrAttr: false,
hasVdomRef: false,
hasVdomRender: false,
hasVdomStyle: false,
hasVdomText: false,
htmlAttrNames: [],
htmlTagNames: [],
htmlParts: [],
isCollectionDependency: false,
isLegacy: false,
localImports: [],
functionalComponentDeps: [],
originalCollectionComponentPath: null,
originalImports: [],
potentialCmpRefs: [],
staticSourceFile: null,
staticSourceFileText: '',
sourceMapPath: null,
sourceMapFileText: null,
};
compilerCtx.moduleMap.set(sourceFilePath, moduleFile);
return moduleFile;
}
};
/**
* Reset a module record, mutating the supplied object to reset values to
* defaults.
*
* @param moduleFile the module record to reset
*/
export const resetModuleLegacy = (moduleFile: d.Module) => {
moduleFile.cmps.length = 0;
moduleFile.coreRuntimeApis.length = 0;
moduleFile.collectionName = null;
moduleFile.dtsFilePath = null;
moduleFile.excludeFromCollection = false;
moduleFile.externalImports.length = 0;
moduleFile.isCollectionDependency = false;
moduleFile.localImports.length = 0;
moduleFile.originalCollectionComponentPath = null;
moduleFile.originalImports.length = 0;
moduleFile.hasVdomXlink = false;
moduleFile.hasVdomAttribute = false;
moduleFile.hasVdomClass = false;
moduleFile.hasVdomFunctional = false;
moduleFile.hasVdomKey = false;
moduleFile.hasVdomListener = false;
moduleFile.hasVdomRef = false;
moduleFile.hasVdomRender = false;
moduleFile.hasVdomStyle = false;
moduleFile.hasVdomText = false;
moduleFile.htmlAttrNames.length = 0;
moduleFile.htmlTagNames.length = 0;
moduleFile.potentialCmpRefs.length = 0;
};
================================================
FILE: src/compiler/build/full-build.ts
================================================
import ts from 'typescript';
import type * as d from '../../declarations';
import { createTsBuildProgram } from '../transpile/create-build-program';
import { build } from './build';
import { BuildContext } from './build-ctx';
/**
* Build a callable function to perform a full build of a Stencil project
* @param config a Stencil configuration to apply to a full build of a Stencil project
* @param compilerCtx the current Stencil compiler context
* @returns the results of a full build of Stencil
*/
export const createFullBuild = async (
config: d.ValidatedConfig,
compilerCtx: d.CompilerCtx,
): Promise => {
return new Promise((resolve) => {
let tsWatchProgram: ts.WatchOfConfigFile = null;
compilerCtx.events.on('fileUpdate', (p) => {
config.logger.debug(`fileUpdate: ${p}`);
compilerCtx.fs.clearFileCache(p);
});
/**
* A function that kicks off the transpilation process for both the TypeScript and Stencil compilers
* @param tsBuilder the manager of the {@link ts.Program} state
*/
const onBuild = async (tsBuilder: ts.BuilderProgram): Promise => {
const buildCtx = new BuildContext(config, compilerCtx);
buildCtx.isRebuild = false;
buildCtx.requiresFullBuild = true;
buildCtx.start();
const result = await build(config, compilerCtx, buildCtx, tsBuilder);
if (result !== null) {
if (tsWatchProgram) {
tsWatchProgram.close();
tsWatchProgram = null;
}
resolve(result);
} else {
// Build returned null, indicating a rebuild is needed (e.g., components.d.ts was just generated).
// Close the current TS program and create a fresh one that includes components.d.ts.
if (tsWatchProgram) {
tsWatchProgram.close();
tsWatchProgram = null;
}
config.logger.debug('Rebuilding with fresh TypeScript program after components.d.ts generation');
createTsBuildProgram(config, onBuild).then((program) => {
tsWatchProgram = program;
});
}
};
createTsBuildProgram(config, onBuild).then((program) => {
tsWatchProgram = program;
});
});
};
================================================
FILE: src/compiler/build/test/build-stats.spec.ts
================================================
import type * as d from '@stencil/core/declarations';
import { mockBuildCtx, mockCompilerCtx, mockValidatedConfig } from '@stencil/core/testing';
import { result } from '@utils';
import { generateBuildResults } from '../build-results';
import { generateBuildStats } from '../build-stats';
describe('generateBuildStats', () => {
let config: d.ValidatedConfig;
let compilerCtx: d.CompilerCtx;
let buildCtx: d.BuildCtx;
beforeEach(() => {
config = mockValidatedConfig();
compilerCtx = mockCompilerCtx(config);
buildCtx = mockBuildCtx(config, compilerCtx);
});
it('should return a structured json object', async () => {
buildCtx.buildResults = generateBuildResults(config, compilerCtx, buildCtx);
const compilerBuildStats = result.unwrap(generateBuildStats(config, buildCtx));
if (compilerBuildStats.hasOwnProperty('timestamp')) {
delete compilerBuildStats.timestamp;
}
if (compilerBuildStats.hasOwnProperty('compiler') && compilerBuildStats.compiler.hasOwnProperty('version')) {
delete compilerBuildStats.compiler.version;
}
expect(compilerBuildStats).toStrictEqual({
app: { bundles: 0, components: 0, entries: 0, fsNamespace: 'testing', namespace: 'Testing', outputs: [] },
collections: [],
compiler: { name: 'in-memory' },
componentGraph: {},
components: [],
entries: [],
formats: { commonjs: [], es5: [], esm: [], esmBrowser: [], system: [] },
options: {
buildEs5: false,
hashFileNames: false,
hashedFileNameLength: 8,
minifyCss: false,
minifyJs: false,
},
rollupResults: {
modules: [],
},
sourceGraph: {},
});
});
it('should return diagnostics if an error is hit', async () => {
buildCtx.buildResults = generateBuildResults(config, compilerCtx, buildCtx);
buildCtx.buildResults.hasError = true;
const diagnostic: d.Diagnostic = {
level: 'error',
type: 'horrible',
messageText: 'the worst error _possible_ has just occurred',
lines: [],
};
buildCtx.buildResults.diagnostics = [diagnostic];
const diagnostics = result.unwrapErr(generateBuildStats(config, buildCtx));
expect(diagnostics).toStrictEqual({
diagnostics: [diagnostic],
});
});
});
================================================
FILE: src/compiler/build/test/write-export-maps.spec.ts
================================================
import { mockBuildCtx, mockValidatedConfig } from '@stencil/core/testing';
import childProcess from 'child_process';
import * as d from '../../../declarations';
import { stubComponentCompilerMeta } from '../../types/tests/ComponentCompilerMeta.stub';
import { writeExportMaps } from '../write-export-maps';
describe('writeExportMaps', () => {
let config: d.ValidatedConfig;
let buildCtx: d.BuildCtx;
let execSyncSpy: jest.SpyInstance;
beforeEach(() => {
config = mockValidatedConfig();
buildCtx = mockBuildCtx(config);
execSyncSpy = jest.spyOn(childProcess, 'execSync').mockImplementation(() => '');
});
afterEach(() => {
jest.clearAllMocks();
});
it('should not generate any exports if there are no output targets', () => {
writeExportMaps(config, buildCtx);
expect(execSyncSpy).toHaveBeenCalledTimes(0);
});
it('should generate the default exports for the lazy build if present', () => {
config.outputTargets = [
{
type: 'dist',
dir: '/dist',
typesDir: '/dist/types',
},
];
writeExportMaps(config, buildCtx);
expect(execSyncSpy).toHaveBeenCalledTimes(3);
expect(execSyncSpy).toHaveBeenCalledWith(`npm pkg set "exports[.][import]"="./dist/index.js"`);
expect(execSyncSpy).toHaveBeenCalledWith(`npm pkg set "exports[.][require]"="./dist/index.cjs.js"`);
expect(execSyncSpy).toHaveBeenCalledWith(`npm pkg set "exports[.][types]"="./dist/types/index.d.ts"`);
});
it('should generate the default exports for the custom elements build if present', () => {
config.outputTargets = [
{
type: 'dist-custom-elements',
dir: '/dist/components',
generateTypeDeclarations: true,
},
];
writeExportMaps(config, buildCtx);
expect(execSyncSpy).toHaveBeenCalledTimes(2);
expect(execSyncSpy).toHaveBeenCalledWith(`npm pkg set "exports[.][import]"="./dist/components/index.js"`);
expect(execSyncSpy).toHaveBeenCalledWith(`npm pkg set "exports[.][types]"="./dist/components/index.d.ts"`);
});
it('should generate the lazy loader exports if the output target is present', () => {
config.rootDir = '/';
config.outputTargets.push({
type: 'dist-lazy-loader',
dir: '/dist/lazy-loader',
empty: true,
esmDir: '/dist/esm',
cjsDir: '/dist/cjs',
componentDts: '/dist/components.d.ts',
});
writeExportMaps(config, buildCtx);
expect(execSyncSpy).toHaveBeenCalledTimes(3);
expect(execSyncSpy).toHaveBeenCalledWith(`npm pkg set "exports[./loader][import]"="./dist/lazy-loader/index.js"`);
expect(execSyncSpy).toHaveBeenCalledWith(`npm pkg set "exports[./loader][require]"="./dist/lazy-loader/index.cjs"`);
expect(execSyncSpy).toHaveBeenCalledWith(`npm pkg set "exports[./loader][types]"="./dist/lazy-loader/index.d.ts"`);
});
it('should generate the custom elements exports if the output target is present', () => {
config.rootDir = '/';
config.outputTargets.push({
type: 'dist-custom-elements',
dir: '/dist/components',
generateTypeDeclarations: true,
});
buildCtx.components = [
stubComponentCompilerMeta({
tagName: 'my-component',
componentClassName: 'MyComponent',
}),
];
writeExportMaps(config, buildCtx);
expect(execSyncSpy).toHaveBeenCalledTimes(4);
expect(execSyncSpy).toHaveBeenCalledWith(
`npm pkg set "exports[./my-component][import]"="./dist/components/my-component.js"`,
);
expect(execSyncSpy).toHaveBeenCalledWith(
`npm pkg set "exports[./my-component][types]"="./dist/components/my-component.d.ts"`,
);
});
it('should generate the custom elements exports for multiple components', () => {
config.rootDir = '/';
config.outputTargets.push({
type: 'dist-custom-elements',
dir: '/dist/components',
generateTypeDeclarations: true,
});
buildCtx.components = [
stubComponentCompilerMeta({
tagName: 'my-component',
componentClassName: 'MyComponent',
}),
stubComponentCompilerMeta({
tagName: 'my-other-component',
componentClassName: 'MyOtherComponent',
}),
];
writeExportMaps(config, buildCtx);
expect(execSyncSpy).toHaveBeenCalledTimes(6);
expect(execSyncSpy).toHaveBeenCalledWith(
`npm pkg set "exports[./my-component][import]"="./dist/components/my-component.js"`,
);
expect(execSyncSpy).toHaveBeenCalledWith(
`npm pkg set "exports[./my-component][types]"="./dist/components/my-component.d.ts"`,
);
expect(execSyncSpy).toHaveBeenCalledWith(
`npm pkg set "exports[./my-other-component][import]"="./dist/components/my-other-component.js"`,
);
expect(execSyncSpy).toHaveBeenCalledWith(
`npm pkg set "exports[./my-other-component][types]"="./dist/components/my-other-component.d.ts"`,
);
});
});
================================================
FILE: src/compiler/build/validate-files.ts
================================================
import type * as d from '../../declarations';
import { validateManifestJson } from '../html/validate-manifest-json';
import { validateBuildPackageJson } from '../types/validate-build-package-json';
/**
* Validate the existence and contents of certain files that were generated after writing the results of the build to
* disk
* @param config the Stencil configuration used for the build
* @param compilerCtx the compiler context associated with the build
* @param buildCtx the build context associated with the current build
* @returns an array containing empty-Promise results
*/
export const validateBuildFiles = (
config: d.ValidatedConfig,
compilerCtx: d.CompilerCtx,
buildCtx: d.BuildCtx,
): Promise<(void | void[] | null)[]> | null => {
if (buildCtx.hasError) {
return null;
}
return Promise.all([
validateBuildPackageJson(config, compilerCtx, buildCtx),
validateManifestJson(config, compilerCtx, buildCtx),
]);
};
================================================
FILE: src/compiler/build/watch-build.ts
================================================
import { isString, resolve } from '@utils';
import { dirname } from 'path';
import type ts from 'typescript';
import type * as d from '../../declarations';
import { compilerRequest } from '../bundle/dev-module';
import {
filesChanged,
hasHtmlChanges,
hasScriptChanges,
hasStyleChanges,
isWatchIgnorePath,
scriptsAdded,
scriptsDeleted,
} from '../fs-watch/fs-watch-rebuild';
import { hasServiceWorkerChanges } from '../service-worker/generate-sw';
import { createTsWatchProgram } from '../transpile/create-watch-program';
import { build } from './build';
import { BuildContext } from './build-ctx';
/**
* This method contains context and functionality for a TS watch build. This is called via
* the compiler when running a build in watch mode (i.e. `stencil build --watch`).
*
* In essence, this method tracks all files that change while the program is running to trigger
* a rebuild of a Stencil project using a {@link ts.EmitAndSemanticDiagnosticsBuilderProgram}.
*
* @param config The validated config for the Stencil project
* @param compilerCtx The compiler context for the project
* @returns An object containing helper methods for the dev-server's watch program
*/
export const createWatchBuild = async (
config: d.ValidatedConfig,
compilerCtx: d.CompilerCtx,
): Promise => {
let isRebuild = false;
let tsWatchProgram: {
program: ts.WatchOfConfigFile;
rebuild: () => void;
};
let closeResolver: Function;
const watchWaiter = new Promise((resolve) => (closeResolver = resolve));
const dirsAdded = new Set();
const dirsDeleted = new Set();
const filesAdded = new Set();
const filesUpdated = new Set();
const filesDeleted = new Set();
/**
* A callback function that is invoked to trigger a rebuild of a Stencil project. This will
* update the build context with the associated file changes (these are used downstream to trigger
* HMR) and then calls the `build()` function to execute the Stencil build.
*
* @param tsBuilder A {@link ts.BuilderProgram} to be passed to the `build()` function.
*/
const onBuild = async (tsBuilder: ts.BuilderProgram) => {
const buildCtx = new BuildContext(config, compilerCtx);
buildCtx.isRebuild = isRebuild;
buildCtx.requiresFullBuild = !isRebuild;
buildCtx.dirsAdded = Array.from(dirsAdded.keys()).sort();
buildCtx.dirsDeleted = Array.from(dirsDeleted.keys()).sort();
buildCtx.filesAdded = Array.from(filesAdded.keys()).sort();
buildCtx.filesUpdated = Array.from(filesUpdated.keys()).sort();
buildCtx.filesDeleted = Array.from(filesDeleted.keys()).sort();
buildCtx.filesChanged = filesChanged(buildCtx);
buildCtx.scriptsAdded = scriptsAdded(buildCtx);
buildCtx.scriptsDeleted = scriptsDeleted(buildCtx);
buildCtx.hasScriptChanges = hasScriptChanges(buildCtx);
buildCtx.hasStyleChanges = hasStyleChanges(buildCtx);
buildCtx.hasHtmlChanges = hasHtmlChanges(config, buildCtx);
buildCtx.hasServiceWorkerChanges = hasServiceWorkerChanges(config, buildCtx);
if (config.flags.debug) {
config.logger.debug(`WATCH_BUILD::watchBuild::onBuild filesAdded: ${formatFilesForDebug(buildCtx.filesAdded)}`);
config.logger.debug(
`WATCH_BUILD::watchBuild::onBuild filesDeleted: ${formatFilesForDebug(buildCtx.filesDeleted)}`,
);
config.logger.debug(
`WATCH_BUILD::watchBuild::onBuild filesUpdated: ${formatFilesForDebug(buildCtx.filesUpdated)}`,
);
config.logger.debug(
`WATCH_BUILD::watchBuild::onBuild filesWritten: ${formatFilesForDebug(buildCtx.filesWritten)}`,
);
}
// Make sure all files in the module map are still in the fs
// Otherwise, we can run into build errors because the compiler can think
// there are two component files with the same tag name
Array.from(compilerCtx.moduleMap.keys()).forEach((key) => {
if (filesUpdated.has(key) || filesDeleted.has(key)) {
// Check if the file exists in the fs
const fileExists = compilerCtx.fs.accessSync(key);
if (!fileExists) {
compilerCtx.moduleMap.delete(key);
}
}
});
// Make sure all added/updated files are watched
// We need to check both added/updates since the TS watch program behaves kinda weird
// and doesn't always handle file renames the same way
new Set([...filesUpdated, ...filesAdded]).forEach((filePath) => {
compilerCtx.addWatchFile(filePath);
});
dirsAdded.clear();
dirsDeleted.clear();
filesAdded.clear();
filesUpdated.clear();
filesDeleted.clear();
emitFsChange(compilerCtx, buildCtx);
buildCtx.start();
// Rebuild the project
const result = await build(config, compilerCtx, buildCtx, tsBuilder);
if (result && !result.hasError) {
isRebuild = true;
}
};
/**
* Utility method for formatting a debug message that must either list a number of files, or the word 'none' if the
* provided list is empty
*
* @param files a list of files, the list may be empty
* @returns the provided list if it is not empty. otherwise, return the word 'none'
*/
const formatFilesForDebug = (files: ReadonlyArray): string => {
/**
* In the created message, it's important that there's no whitespace prior to the file name.
* Stencil's logger will split messages by whitespace according to the width of the terminal window.
* Since file names can be fully qualified paths (and therefore quite long), putting whitespace between a '-' and
* the path can lead to formatted messages where the '-' is on its own line
*/
return files.length > 0 ? files.map((filename: string) => `-${filename}`).join('\n') : 'none';
};
/**
* Utility method to start/construct the watch program. This will mark
* all relevant files to be watched and then call a method to build the TS
* program responsible for building the project.
*
* @returns A promise of the result of creating the watch program.
*/
const start = async () => {
/**
* Stencil watches the following directories for changes:
*/
await Promise.all([
/**
* the `srcDir` directory, e.g. component files
*/
watchFiles(compilerCtx, config.srcDir),
/**
* the root directory, e.g. `stencil.config.ts`
*/
watchFiles(compilerCtx, config.rootDir, {
recursive: false,
}),
/**
* the external directories, defined in `watchExternalDirs`, e.g. `node_modules`
*/
...(config.watchExternalDirs || []).map((dir) => watchFiles(compilerCtx, dir)),
]);
tsWatchProgram = await createTsWatchProgram(config, onBuild);
return watchWaiter;
};
/**
* A map of absolute directory paths and their associated {@link d.CompilerFileWatcher} (which contains
* the ability to teardown the watcher for the specific directory)
*/
const watchingDirs = new Map();
/**
* A map of absolute file paths and their associated {@link d.CompilerFileWatcher} (which contains
* the ability to teardown the watcher for the specific file)
*/
const watchingFiles = new Map();
/**
* Callback method that will execute whenever TS alerts us that a file change
* has occurred. This will update the appropriate set with the file path based on the
* type of change, and then will kick off a rebuild of the project.
*
* @param filePath The absolute path to the file in the Stencil project
* @param eventKind The type of file change that occurred (update, add, delete)
*/
const onFsChange: d.CompilerFileWatcherCallback = (filePath, eventKind) => {
if (tsWatchProgram && !isWatchIgnorePath(config, filePath)) {
updateCompilerCtxCache(config, compilerCtx, filePath, eventKind);
switch (eventKind) {
case 'dirAdd':
dirsAdded.add(filePath);
break;
case 'dirDelete':
dirsDeleted.add(filePath);
break;
case 'fileAdd':
filesAdded.add(filePath);
break;
case 'fileUpdate':
filesUpdated.add(filePath);
break;
case 'fileDelete':
filesDeleted.add(filePath);
break;
}
config.logger.debug(
`WATCH_BUILD::fs_event_change - type=${eventKind}, path=${filePath}, time=${new Date().getTime()}`,
);
// Trigger a rebuild of the project
tsWatchProgram.rebuild();
}
};
/**
* Callback method that will execute when TS alerts us that a directory modification has occurred.
* This will just call the `onFsChange()` callback method with the same arguments.
*
* @param filePath The absolute path to the file in the Stencil project
* @param eventKind The type of file change that occurred (update, add, delete)
*/
const onDirChange: d.CompilerFileWatcherCallback = (filePath, eventKind) => {
if (eventKind != null) {
onFsChange(filePath, eventKind);
}
};
/**
* Utility method to teardown the TS watch program and close/clear all watched files.
*
* @returns An object with the `exitCode` status of the teardown.
*/
const close = async () => {
watchingDirs.forEach((w) => w.close());
watchingFiles.forEach((w) => w.close());
watchingDirs.clear();
watchingFiles.clear();
if (tsWatchProgram) {
tsWatchProgram.program.close();
tsWatchProgram = null;
}
const watcherCloseResults: d.WatcherCloseResults = {
exitCode: 0,
};
closeResolver(watcherCloseResults);
return watcherCloseResults;
};
const request = async (data: d.CompilerRequest) => compilerRequest(config, compilerCtx, data);
// Add a definition to the `compilerCtx` for `addWatchFile`
// This method will add the specified file path to the watched files collection and instruct
// the `CompilerSystem` what to do when a file change occurs (the `onFsChange()` callback)
compilerCtx.addWatchFile = (filePath) => {
if (isString(filePath) && !watchingFiles.has(filePath) && !isWatchIgnorePath(config, filePath)) {
watchingFiles.set(filePath, config.sys.watchFile(filePath, onFsChange));
}
};
// Add a definition to the `compilerCtx` for `addWatchDir`
// This method will add the specified file path to the watched directories collection and instruct
// the `CompilerSystem` what to do when a directory change occurs (the `onDirChange()` callback)
compilerCtx.addWatchDir = (dirPath, recursive) => {
if (isString(dirPath) && !watchingDirs.has(dirPath) && !isWatchIgnorePath(config, dirPath)) {
watchingDirs.set(dirPath, config.sys.watchDirectory(dirPath, onDirChange, recursive));
}
};
// When the compiler system destroys, we need to also destroy this watch program
config.sys.addDestroy(close);
return {
start,
close,
on: compilerCtx.events.on,
request,
};
};
/**
* A list of directories that are excluded from being watched for changes.
*/
const EXCLUDE_DIRS = ['.cache', '.git', '.github', '.stencil', '.vscode', 'node_modules'];
/**
* A list of file extensions that are excluded from being watched for changes.
*/
const EXCLUDE_EXTENSIONS = [
'.md',
'.markdown',
'.txt',
'.spec.ts',
'.spec.tsx',
'.e2e.ts',
'.e2e.tsx',
'.gitignore',
'.editorconfig',
];
/**
* Marks all root files of a Stencil project to be watched for changes. Whenever
* one of these files is determined as changed (according to TS), a rebuild of the project will execute.
*
* @param compilerCtx The compiler context for the Stencil project
* @param dir The directory to watch for changes
* @param options The options to watch files in the directory
* @param options.recursive Whether to watch files recursively
* @param options.excludeDirNames A list of directories to exclude from being watched
* @param options.excludeExtensions A list of file extensions to exclude from being watched for changes
*/
const watchFiles = async (
compilerCtx: d.CompilerCtx,
dir: string,
options?: {
recursive?: boolean;
excludeDirNames?: string[];
excludeExtensions?: string[];
},
) => {
const recursive = options?.recursive ?? true;
const excludeDirNames = options?.excludeDirNames ?? EXCLUDE_DIRS;
const excludeExtensions = options?.excludeExtensions ?? EXCLUDE_EXTENSIONS;
/**
* non-src files that cause a rebuild
* mainly for root level config files, and getting an event when they change
*/
const rootFiles = await compilerCtx.fs.readdir(dir, {
recursive,
excludeDirNames,
excludeExtensions,
});
/**
* If the directory is watched recursively, we need to watch the directory itself.
*/
if (recursive) {
compilerCtx.addWatchDir(dir, true);
}
/**
* Iterate over each file in the collection (filter out directories) and add
* a watcher for each
*/
rootFiles.filter(({ isFile }) => isFile).forEach(({ absPath }) => compilerCtx.addWatchFile(absPath));
};
const emitFsChange = (compilerCtx: d.CompilerCtx, buildCtx: BuildContext) => {
if (
buildCtx.dirsAdded.length > 0 ||
buildCtx.dirsDeleted.length > 0 ||
buildCtx.filesUpdated.length > 0 ||
buildCtx.filesAdded.length > 0 ||
buildCtx.filesDeleted.length > 0
) {
compilerCtx.events.emit('fsChange', {
dirsAdded: buildCtx.dirsAdded.slice(),
dirsDeleted: buildCtx.dirsDeleted.slice(),
filesUpdated: buildCtx.filesUpdated.slice(),
filesAdded: buildCtx.filesAdded.slice(),
filesDeleted: buildCtx.filesDeleted.slice(),
});
}
};
const updateCompilerCtxCache = (
config: d.ValidatedConfig,
compilerCtx: d.CompilerCtx,
path: string,
kind: d.CompilerFileWatcherEvent,
) => {
compilerCtx.fs.clearFileCache(path);
compilerCtx.changedFiles.add(path);
if (kind === 'fileDelete') {
compilerCtx.moduleMap.delete(path);
} else if (kind === 'dirDelete') {
const fsRootDir = resolve('/');
compilerCtx.moduleMap.forEach((_, moduleFilePath) => {
let moduleAncestorDir = dirname(moduleFilePath);
for (let i = 0; i < 50; i++) {
if (moduleAncestorDir === config.rootDir || moduleAncestorDir === fsRootDir) {
break;
}
if (moduleAncestorDir === path) {
compilerCtx.fs.clearFileCache(moduleFilePath);
compilerCtx.moduleMap.delete(moduleFilePath);
compilerCtx.changedFiles.add(moduleFilePath);
break;
}
moduleAncestorDir = dirname(moduleAncestorDir);
}
});
}
};
================================================
FILE: src/compiler/build/write-build.ts
================================================
import { catchError } from '@utils';
import * as d from '../../declarations';
import { outputServiceWorkers } from '../output-targets/output-service-workers';
import { validateBuildFiles } from './validate-files';
import { writeExportMaps } from './write-export-maps';
/**
* Writes files to disk as a result of compilation
* @param config the Stencil configuration used for the build
* @param compilerCtx the compiler context associated with the build
* @param buildCtx the build context associated with the current build
*/
export const writeBuild = async (
config: d.ValidatedConfig,
compilerCtx: d.CompilerCtx,
buildCtx: d.BuildCtx,
): Promise => {
const timeSpan = buildCtx.createTimeSpan(`writeBuildFiles started`, true);
let totalFilesWrote = 0;
try {
// commit all the `writeFile`, `mkdir`, `rmdir` and `unlink` operations to disk
const commitResults = await compilerCtx.fs.commit();
// get the results from the write to disk commit
buildCtx.filesWritten = commitResults.filesWritten;
buildCtx.filesDeleted = commitResults.filesDeleted;
buildCtx.dirsDeleted = commitResults.dirsDeleted;
buildCtx.dirsAdded = commitResults.dirsAdded;
totalFilesWrote = commitResults.filesWritten.length;
// successful write
// kick off writing the cached file stuff
await compilerCtx.cache.commit();
buildCtx.debug(`in-memory-fs: ${compilerCtx.fs.getMemoryStats()}`);
buildCtx.debug(`cache: ${compilerCtx.cache.getMemoryStats()}`);
if (config.generateExportMaps) {
writeExportMaps(config, buildCtx);
}
await outputServiceWorkers(config, buildCtx);
await validateBuildFiles(config, compilerCtx, buildCtx);
} catch (e: any) {
catchError(buildCtx.diagnostics, e);
}
timeSpan.finish(`writeBuildFiles finished, files wrote: ${totalFilesWrote}`);
};
================================================
FILE: src/compiler/build/write-export-maps.ts
================================================
import {
isEligiblePrimaryPackageOutputTarget,
isOutputTargetDistCustomElements,
isOutputTargetDistLazyLoader,
} from '@utils';
import { relative } from '@utils';
import { execSync } from 'child_process';
import * as d from '../../declarations';
import { PRIMARY_PACKAGE_TARGET_CONFIGS } from '../types/validate-primary-package-output-target';
/**
* Create export map entry point definitions for the `package.json` file using the npm CLI.
* This will generate a root entry point for the package, as well as entry points for each component and
* the lazy loader (if applicable).
*
* @param config The validated Stencil config
* @param buildCtx The build context containing the components to generate export maps for
*/
export const writeExportMaps = (config: d.ValidatedConfig, buildCtx: d.BuildCtx) => {
const eligiblePrimaryTargets = config.outputTargets.filter(isEligiblePrimaryPackageOutputTarget);
if (eligiblePrimaryTargets.length > 0) {
const primaryTarget =
eligiblePrimaryTargets.find((o) => o.isPrimaryPackageOutputTarget) ?? eligiblePrimaryTargets[0];
const outputTargetConfig = PRIMARY_PACKAGE_TARGET_CONFIGS[primaryTarget.type];
if (outputTargetConfig.getModulePath) {
const importPath = outputTargetConfig.getModulePath(config.rootDir, primaryTarget.dir!);
if (importPath) {
execSync(`npm pkg set "exports[.][import]"="${importPath}"`);
}
}
if (outputTargetConfig.getMainPath) {
const requirePath = outputTargetConfig.getMainPath(config.rootDir, primaryTarget.dir!);
if (requirePath) {
execSync(`npm pkg set "exports[.][require]"="${requirePath}"`);
}
}
if (outputTargetConfig.getTypesPath) {
const typesPath = outputTargetConfig.getTypesPath(config.rootDir, primaryTarget);
if (typesPath) {
execSync(`npm pkg set "exports[.][types]"="${typesPath}"`);
}
}
}
const distLazyLoader = config.outputTargets.find(isOutputTargetDistLazyLoader);
if (distLazyLoader != null) {
// Calculate relative path from project root to lazy-loader output directory
let outDir = relative(config.rootDir, distLazyLoader.dir);
if (!outDir.startsWith('.')) {
outDir = './' + outDir;
}
execSync(`npm pkg set "exports[./loader][import]"="${outDir}/index.js"`);
execSync(`npm pkg set "exports[./loader][require]"="${outDir}/index.cjs"`);
execSync(`npm pkg set "exports[./loader][types]"="${outDir}/index.d.ts"`);
}
const distCustomElements = config.outputTargets.find(isOutputTargetDistCustomElements);
if (distCustomElements != null) {
// Calculate relative path from project root to custom elements output directory
let outDir = relative(config.rootDir, distCustomElements.dir!);
if (!outDir.startsWith('.')) {
outDir = './' + outDir;
}
buildCtx.components.forEach((cmp) => {
execSync(`npm pkg set "exports[./${cmp.tagName}][import]"="${outDir}/${cmp.tagName}.js"`);
if (distCustomElements.generateTypeDeclarations) {
execSync(`npm pkg set "exports[./${cmp.tagName}][types]"="${outDir}/${cmp.tagName}.d.ts"`);
}
});
}
};
================================================
FILE: src/compiler/bundle/app-data-plugin.ts
================================================
import { createJsVarName, isString, loadTypeScriptDiagnostics, normalizePath } from '@utils';
import MagicString from 'magic-string';
import { basename } from 'path';
import type { LoadResult, Plugin, ResolveIdResult, TransformResult } from 'rollup';
import ts from 'typescript';
import type * as d from '../../declarations';
import type { BundlePlatform } from './bundle-interface';
import { removeCollectionImports } from '../transformers/remove-collection-imports';
import { APP_DATA_CONDITIONAL, STENCIL_APP_DATA_ID, STENCIL_APP_GLOBALS_ID } from './entry-alias-ids';
/**
* A Rollup plugin which bundles application data.
*
* @param config the Stencil configuration for a particular project
* @param compilerCtx the current compiler context
* @param buildCtx the current build context
* @param buildConditionals the set build conditionals for the build
* @param platform the platform that is being built
* @returns a Rollup plugin which carries out the necessary work
*/
export const appDataPlugin = (
config: d.ValidatedConfig,
compilerCtx: d.CompilerCtx,
buildCtx: d.BuildCtx,
buildConditionals: d.BuildConditionals,
platform: BundlePlatform,
): Plugin => {
if (!platform) {
return {
name: 'appDataPlugin',
};
}
const globalScripts = getGlobalScriptData(config, compilerCtx);
return {
name: 'appDataPlugin',
resolveId(id: string, importer: string | undefined): ResolveIdResult {
if (id === STENCIL_APP_DATA_ID || id === STENCIL_APP_GLOBALS_ID) {
if (platform === 'worker') {
this.error('@stencil/core packages cannot be imported from a worker.');
}
if (platform === 'hydrate' || STENCIL_APP_GLOBALS_ID) {
// hydrate will always bundle app-data and runtime
// and the load() fn will build a custom globals import
return id;
} else if (platform === 'client' && importer && importer.endsWith(APP_DATA_CONDITIONAL)) {
// since the importer ends with ?app-data=conditional we know that
// we need to build custom app-data based off of component metadata
// return the same "id" so that the "load()" method knows to
// build custom app-data
return id;
}
// for a client build that does not have ?app-data=conditional at the end then we
// do not want to create custom app-data, but should use the default
}
return null;
},
async load(id: string): Promise {
if (id === STENCIL_APP_GLOBALS_ID) {
const s = new MagicString(``);
appendGlobalScripts(globalScripts, s);
await appendGlobalStyles(buildCtx, s, platform);
return s.toString();
}
if (id === STENCIL_APP_DATA_ID) {
// build custom app-data based off of component metadata
const s = new MagicString(``);
appendNamespace(config, s);
appendBuildConditionals(config, buildConditionals, s);
appendEnv(config, s);
return s.toString();
}
if (id !== config.globalScript) {
return null;
}
const module = compilerCtx.moduleMap.get(config.globalScript);
if (!module) {
return null;
} else if (!module.sourceMapFileText) {
return {
code: module.staticSourceFileText,
map: null,
};
}
const sourceMap: d.SourceMap = JSON.parse(module.sourceMapFileText);
sourceMap.sources = sourceMap.sources.map((src) => basename(src));
return { code: module.staticSourceFileText, map: sourceMap };
},
transform(code: string, id: string): TransformResult {
id = normalizePath(id);
if (globalScripts.some((s) => s.path === id)) {
const program = this.parse(code, {});
const needsDefault = !(program as any).body.some((s: any) => s.type === 'ExportDefaultDeclaration');
if (needsDefault) {
const diagnostic: d.Diagnostic = {
level: 'warn',
type: 'build',
header: 'Missing default export in globalScript',
messageText: `globalScript should export a default function.\nSee: https://stenciljs.com/docs/config#globalscript`,
relFilePath: id,
lines: [],
};
buildCtx.diagnostics.push(diagnostic);
}
const defaultExport = needsDefault ? '\nexport const globalFn = () => {};\nexport default globalFn;' : '';
code = code + defaultExport;
const compilerOptions: ts.CompilerOptions = { ...config.tsCompilerOptions };
compilerOptions.module = ts.ModuleKind.ESNext;
const results = ts.transpileModule(code, {
compilerOptions,
fileName: id,
transformers: {
after: [removeCollectionImports(compilerCtx)],
},
});
buildCtx.diagnostics.push(...loadTypeScriptDiagnostics(results.diagnostics));
if (config.sourceMap) {
// generate the sourcemap for global script
const codeMs = new MagicString(code);
const codeMap = codeMs.generateMap({
source: id,
// this is the name of the sourcemap, not to be confused with the `file` field in a generated sourcemap
file: id + '.map',
includeContent: true,
hires: true,
});
return {
code: results.outputText,
map: {
...codeMap,
// MagicString changed their types in this PR: https://github.com/Rich-Harris/magic-string/pull/235
// so that their `sourcesContent` is of type `(string | null)[]`. But, it will only return `[null]` if
// `includeContent` is set to `false`. Since we explicitly set `includeContent: true`, we can override
// the type to satisfy Rollup's type expectation
sourcesContent: codeMap.sourcesContent as string[],
},
};
}
return { code: results.outputText };
}
return null;
},
};
};
export const getGlobalScriptData = (config: d.ValidatedConfig, compilerCtx: d.CompilerCtx) => {
const globalScripts: GlobalScript[] = [];
if (isString(config.globalScript)) {
const mod = compilerCtx.moduleMap.get(config.globalScript);
const globalScript = compilerCtx.version === 2 ? config.globalScript : mod && mod.jsFilePath;
if (globalScript) {
globalScripts.push({
defaultName: createJsVarName(config.namespace + 'GlobalScript'),
path: normalizePath(globalScript),
});
}
}
compilerCtx.collections.forEach((collection) => {
if (collection.global != null && isString(collection.global.sourceFilePath)) {
let defaultName = createJsVarName(collection.collectionName + 'GlobalScript');
if (globalScripts.some((s) => s.defaultName === defaultName)) {
defaultName += globalScripts.length;
}
globalScripts.push({
defaultName,
path: normalizePath(collection.global.sourceFilePath),
});
}
});
return globalScripts;
};
const appendGlobalScripts = (globalScripts: GlobalScript[], s: MagicString) => {
if (globalScripts.length === 1) {
s.prepend(`import * as appGlobalScriptNs from '${globalScripts[0].path}';\n`);
s.prepend(`const appGlobalScript = appGlobalScriptNs.default || (() => {});\n`);
s.append(`export const globalScripts = appGlobalScript;\n`);
} else if (globalScripts.length > 1) {
globalScripts.forEach((globalScript) => {
s.prepend(`import * as ${globalScript.defaultName}Ns from '${globalScript.path}';\n`);
s.prepend(`const ${globalScript.defaultName} = ${globalScript.defaultName}Ns.default || (() => {});\n`);
});
s.append(`export const globalScripts = () => {\n`);
s.append(` return Promise.all([\n`);
globalScripts.forEach((globalScript) => {
s.append(` ${globalScript.defaultName}(),\n`);
});
s.append(` ]);\n`);
s.append(`};\n`);
} else {
s.append(`export const globalScripts = () => {};\n`);
}
};
/**
* Appends the global styles to the MagicString.
*
* @param buildCtx the build context
* @param s the MagicString to append the global styles onto
* @param platform the platform that is being built
*/
const appendGlobalStyles = async (buildCtx: d.BuildCtx, s: MagicString, platform: BundlePlatform) => {
const { addGlobalStyleToComponents } = buildCtx.config.extras;
const shouldIncludeGlobalStyles =
addGlobalStyleToComponents === true || (addGlobalStyleToComponents === 'client' && platform === 'client');
const globalStyles = buildCtx.config.globalStyle && shouldIncludeGlobalStyles ? await buildCtx.stylesPromise : '';
s.append(`export const globalStyles = ${JSON.stringify(globalStyles)};\n`);
};
/**
* Generates the `BUILD` constant that is used at compile-time in a Stencil project
*
* **This function mutates the provided {@link MagicString} argument**
*
* @param config the configuration associated with the Stencil project
* @param buildConditionals the build conditionals to serialize into a JS object
* @param s a `MagicString` to append the generated constant onto
*/
export const appendBuildConditionals = (
config: d.ValidatedConfig,
buildConditionals: d.BuildConditionals,
s: MagicString,
): void => {
const buildData = Object.keys(buildConditionals)
.sort()
.map((key) => key + ': ' + JSON.stringify((buildConditionals as any)[key]))
.join(', ');
s.append(`export const BUILD = /* ${config.fsNamespace} */ { ${buildData} };\n`);
};
const appendEnv = (config: d.ValidatedConfig, s: MagicString) => {
s.append(`export const Env = /* ${config.fsNamespace} */ ${JSON.stringify(config.env)};\n`);
};
const appendNamespace = (config: d.ValidatedConfig, s: MagicString) => {
s.append(`export const NAMESPACE = '${config.fsNamespace}';\n`);
};
interface GlobalScript {
defaultName: string;
path: string;
}
================================================
FILE: src/compiler/bundle/bundle-interface.ts
================================================
import type { PreserveEntrySignaturesOption } from 'rollup';
import type { SourceFile, TransformerFactory } from 'typescript';
import type { BuildConditionals } from '../../declarations';
/**
* Options for bundled output passed on Rollup
*
* This covers the ID for the bundle, the platform it runs on, input modules,
* and more
*/
export interface BundleOptions {
id: string;
conditionals?: BuildConditionals;
/**
* When `true`, all `@stencil/core/*` packages will be treated as external
* and omitted from the generated bundle.
*/
externalRuntime?: boolean;
platform: BundlePlatform;
/**
* A collection of TypeScript transformation factories to apply during the "before" stage of the TypeScript
* compilation pipeline (before built-in .js transformations)
*/
customBeforeTransformers?: TransformerFactory[];
/**
* This is equivalent to the Rollup `input` configuration option. It's
* an object mapping names to entry points which tells Rollup to bundle
* each thing up as a separate output chunk.
*
* @see {@link https://rollupjs.org/guide/en/#input}
*/
inputs: { [entryKey: string]: string };
/**
* A map of strings which are passed to the Stencil-specific loader plugin
* which we use to resolve the imports of Stencil project files when building
* with Rollup.
*
* @see {@link loader-plugin:loaderPlugin}
*/
loader?: { [id: string]: string };
/**
* Duplicate of Rollup's `inlineDynamicImports` output option.
*
* Creates dynamic imports (i.e. `import()` calls) as a part of the same
* chunk being bundled. Rather than being created as separate chunks.
*
* @see {@link https://rollupjs.org/guide/en/#outputinlinedynamicimports}
*/
inlineDynamicImports?: boolean;
inlineWorkers?: boolean;
/**
* Duplicate of Rollup's `preserveEntrySignatures` option.
*
* "Controls if Rollup tries to ensure that entry chunks have the same
* exports as the underlying entry module."
*
* @see {@link https://rollupjs.org/guide/en/#preserveentrysignatures}
*/
preserveEntrySignatures?: PreserveEntrySignaturesOption;
}
export type BundlePlatform = 'client' | 'hydrate' | 'worker';
================================================
FILE: src/compiler/bundle/bundle-output.ts
================================================
import rollupCommonjsPlugin from '@rollup/plugin-commonjs';
import rollupJsonPlugin from '@rollup/plugin-json';
import rollupNodeResolvePlugin from '@rollup/plugin-node-resolve';
import rollupReplacePlugin from '@rollup/plugin-replace';
import { createOnWarnFn, isString, loadRollupDiagnostics } from '@utils';
import { type ObjectHook, PluginContext, rollup, RollupOptions, TreeshakingOptions } from 'rollup';
import type * as d from '../../declarations';
import { lazyComponentPlugin } from '../output-targets/dist-lazy/lazy-component-plugin';
import { appDataPlugin } from './app-data-plugin';
import type { BundleOptions } from './bundle-interface';
import { coreResolvePlugin } from './core-resolve-plugin';
import { devNodeModuleResolveId } from './dev-node-module-resolve';
import { extFormatPlugin } from './ext-format-plugin';
import { extTransformsPlugin } from './ext-transforms-plugin';
import { fileLoadPlugin } from './file-load-plugin';
import { loaderPlugin } from './loader-plugin';
import { pluginHelper } from './plugin-helper';
import { serverPlugin } from './server-plugin';
import { resolveIdWithTypeScript, typescriptPlugin } from './typescript-plugin';
import { userIndexPlugin } from './user-index-plugin';
import { workerPlugin } from './worker-plugin';
export const bundleOutput = async (
config: d.ValidatedConfig,
compilerCtx: d.CompilerCtx,
buildCtx: d.BuildCtx,
bundleOpts: BundleOptions,
) => {
try {
const rollupOptions = getRollupOptions(config, compilerCtx, buildCtx, bundleOpts);
const rollupBuild = await rollup(rollupOptions);
compilerCtx.rollupCache.set(bundleOpts.id, rollupBuild.cache);
return rollupBuild;
} catch (e: any) {
if (!buildCtx.hasError) {
// TODO(STENCIL-353): Implement a type guard that balances using our own copy of Rollup types (which are
// breakable) and type safety (so that the error variable may be something other than `any`)
loadRollupDiagnostics(config, compilerCtx, buildCtx, e);
}
}
return undefined;
};
/**
* Build the rollup options that will be used to transpile, minify, and otherwise transform a Stencil project
* @param config the Stencil configuration for the project
* @param compilerCtx the current compiler context
* @param buildCtx a context object containing information about the current build
* @param bundleOpts Rollup bundling options to apply to the base configuration setup by this function
* @returns the rollup options to be used
*/
export const getRollupOptions = (
config: d.ValidatedConfig,
compilerCtx: d.CompilerCtx,
buildCtx: d.BuildCtx,
bundleOpts: BundleOptions,
): RollupOptions => {
const nodeResolvePlugin = rollupNodeResolvePlugin({
mainFields: ['collection:main', 'jsnext:main', 'es2017', 'es2015', 'module', 'main'],
browser: bundleOpts.platform !== 'hydrate',
rootDir: config.rootDir,
exportConditions: ['default', 'module', 'import', 'require'],
extensions: ['.tsx', '.ts', '.mts', '.cts', '.js', '.mjs', '.cjs', '.json', '.d.ts', '.d.mts', '.d.cts'],
...config.nodeResolve,
});
// @ts-expect-error - this is required now.
nodeResolvePlugin.resolve = async function () {
// Investigate if we can use this to leverage Stencil's in-memory fs
};
// @ts-expect-error - this is required now.
nodeResolvePlugin.warn = (log) => {
const onWarn = createOnWarnFn(buildCtx.diagnostics);
if (typeof log === 'string') {
onWarn({ message: log });
} else if (typeof log === 'function') {
const result = log();
if (typeof result === 'string') {
onWarn({ message: result });
} else {
onWarn(result);
}
} else {
onWarn(log);
}
};
assertIsObjectHook(nodeResolvePlugin.resolveId);
// remove default 'post' order
nodeResolvePlugin.resolveId.order = null;
const orgNodeResolveId = nodeResolvePlugin.resolveId.handler;
const orgNodeResolveId2 = (nodeResolvePlugin.resolveId.handler = async function (importee: string, importer: string) {
const [realImportee, query] = importee.split('?');
const resolved = await orgNodeResolveId.call(
nodeResolvePlugin as unknown as PluginContext,
realImportee,
importer,
{
attributes: {},
isEntry: true,
},
);
if (resolved) {
if (isString(resolved)) {
return query ? resolved + '?' + query : resolved;
}
return {
...resolved,
id: query ? resolved.id + '?' + query : resolved.id,
};
}
return resolved;
});
if (config.devServer?.experimentalDevModules) {
nodeResolvePlugin.resolveId = async function (importee: string, importer: string) {
const resolvedId = await orgNodeResolveId2.call(
nodeResolvePlugin as unknown as PluginContext,
importee,
importer,
);
return devNodeModuleResolveId(config, compilerCtx.fs, resolvedId, importee);
};
}
const beforePlugins = config.rollupPlugins.before || [];
const afterPlugins = config.rollupPlugins.after || [];
const rollupOptions: RollupOptions = {
input: bundleOpts.inputs,
output: {
inlineDynamicImports: bundleOpts.inlineDynamicImports ?? false,
},
plugins: [
coreResolvePlugin(
config,
compilerCtx,
bundleOpts.platform,
!!bundleOpts.externalRuntime,
bundleOpts.conditionals?.lazyLoad ?? false,
),
appDataPlugin(config, compilerCtx, buildCtx, bundleOpts.conditionals, bundleOpts.platform),
lazyComponentPlugin(buildCtx),
loaderPlugin(bundleOpts.loader),
userIndexPlugin(config, compilerCtx),
typescriptPlugin(compilerCtx, bundleOpts, config),
extFormatPlugin(config),
extTransformsPlugin(config, compilerCtx, buildCtx),
workerPlugin(config, compilerCtx, buildCtx, bundleOpts.platform, !!bundleOpts.inlineWorkers),
serverPlugin(config, bundleOpts.platform),
...beforePlugins,
nodeResolvePlugin,
resolveIdWithTypeScript(config, compilerCtx),
rollupCommonjsPlugin({
include: /node_modules/,
sourceMap: config.sourceMap,
transformMixedEsModules: false,
...config.commonjs,
}),
...afterPlugins,
pluginHelper(config, buildCtx, bundleOpts.platform),
rollupJsonPlugin({
preferConst: true,
}),
rollupReplacePlugin({
'process.env.NODE_ENV': config.devMode ? '"development"' : '"production"',
preventAssignment: true,
}),
fileLoadPlugin(compilerCtx.fs),
],
treeshake: getTreeshakeOption(config, bundleOpts),
preserveEntrySignatures: bundleOpts.preserveEntrySignatures ?? 'strict',
onwarn: createOnWarnFn(buildCtx.diagnostics),
cache: compilerCtx.rollupCache.get(bundleOpts.id),
external: config.rollupConfig.inputOptions.external,
maxParallelFileOps: config.rollupConfig.inputOptions.maxParallelFileOps,
};
return rollupOptions;
};
const getTreeshakeOption = (config: d.ValidatedConfig, bundleOpts: BundleOptions): TreeshakingOptions | boolean => {
if (bundleOpts.platform === 'hydrate') {
return {
propertyReadSideEffects: false,
tryCatchDeoptimization: false,
};
}
const treeshake =
!config.devMode && config.rollupConfig.inputOptions.treeshake !== false
? {
propertyReadSideEffects: false,
tryCatchDeoptimization: false,
}
: false;
return treeshake;
};
function assertIsObjectHook(hook: ObjectHook): asserts hook is { handler: T; order?: 'pre' | 'post' | null } {
if (typeof hook !== 'object') throw new Error(`expected the rollup plugin hook ${hook} to be an object`);
}
================================================
FILE: src/compiler/bundle/constants.ts
================================================
export const DEV_MODULE_CACHE_BUSTER = 0;
export const DEV_MODULE_DIR = `~dev-module`;
================================================
FILE: src/compiler/bundle/core-resolve-plugin.ts
================================================
import { isRemoteUrl, join, normalizeFsPath, normalizePath } from '@utils';
import { dirname } from 'path';
import type { Plugin } from 'rollup';
import type * as d from '../../declarations';
import type { BundlePlatform } from './bundle-interface';
import { HYDRATED_CSS } from '../../runtime/runtime-constants';
import { fetchModuleAsync } from '../sys/fetch/fetch-module-async';
import { getStencilModuleUrl, packageVersions } from '../sys/fetch/fetch-utils';
import {
APP_DATA_CONDITIONAL,
STENCIL_CORE_ID,
STENCIL_INTERNAL_CLIENT_ID,
STENCIL_INTERNAL_CLIENT_PATCH_BROWSER_ID,
STENCIL_INTERNAL_HYDRATE_ID,
STENCIL_INTERNAL_ID,
STENCIL_JSX_DEV_RUNTIME_ID,
STENCIL_JSX_RUNTIME_ID,
} from './entry-alias-ids';
export const coreResolvePlugin = (
config: d.ValidatedConfig,
compilerCtx: d.CompilerCtx,
platform: BundlePlatform,
externalRuntime: boolean,
lazyLoad: boolean,
): Plugin => {
const compilerExe = config.sys.getCompilerExecutingPath();
const internalClient = getStencilInternalModule(config, compilerExe, 'client/index.js');
const internalClientPatchBrowser = getStencilInternalModule(config, compilerExe, 'client/patch-browser.js');
const internalHydrate = getStencilInternalModule(config, compilerExe, 'hydrate/index.js');
return {
name: 'coreResolvePlugin',
resolveId(id) {
if (id === STENCIL_CORE_ID || id === STENCIL_INTERNAL_ID) {
if (platform === 'client') {
if (externalRuntime) {
return {
id: STENCIL_INTERNAL_CLIENT_ID,
external: true,
};
}
if (lazyLoad) {
// with a lazy / dist build, add `?app-data=conditional` as an identifier to ensure we don't
// use the default app-data, but build a custom one based on component meta
return internalClient + APP_DATA_CONDITIONAL;
}
// for a non-lazy / dist-custom-elements build, use the default, complete core.
// This ensures all features are available for any importer library
return internalClient;
}
if (platform === 'hydrate') {
return internalHydrate;
}
}
if (id === STENCIL_INTERNAL_CLIENT_ID) {
if (externalRuntime) {
// not bundling the client runtime and the user's component together this
// must be the custom elements build, where @stencil/core/internal/client
// is an import, rather than bundling
return {
id: STENCIL_INTERNAL_CLIENT_ID,
external: true,
};
}
// importing @stencil/core/internal/client directly, so it shouldn't get
// the custom app-data conditionals
return internalClient;
}
if (id === STENCIL_INTERNAL_CLIENT_PATCH_BROWSER_ID) {
if (externalRuntime) {
return {
id: STENCIL_INTERNAL_CLIENT_PATCH_BROWSER_ID,
external: true,
};
}
return internalClientPatchBrowser;
}
if (id === STENCIL_INTERNAL_HYDRATE_ID) {
return internalHydrate;
}
// Handle jsx-runtime and jsx-dev-runtime imports
// These must resolve to the same internal client path as @stencil/core
// to prevent Rollup from bundling duplicate runtime code with different
// minified property names, which causes VNode property mismatches during hydration
if (id === STENCIL_JSX_RUNTIME_ID || id === STENCIL_JSX_DEV_RUNTIME_ID) {
if (platform === 'client') {
if (externalRuntime) {
return {
id: STENCIL_INTERNAL_CLIENT_ID,
external: true,
};
}
if (lazyLoad) {
// with a lazy / dist build, add `?app-data=conditional` as an identifier to ensure we don't
// use the default app-data, but build a custom one based on component meta
return internalClient + APP_DATA_CONDITIONAL;
}
// for a non-lazy / dist-custom-elements build, use the default, complete core.
return internalClient;
}
if (platform === 'hydrate') {
return internalHydrate;
}
}
return null;
},
async load(filePath) {
if (filePath && !filePath.startsWith('\0')) {
filePath = normalizeFsPath(filePath);
if (filePath === internalClient || filePath === internalHydrate) {
if (platform === 'worker') {
return `
export const Build = {
isDev: ${config.devMode},
isBrowser: true,
isServer: false,
isTesting: false,
};`;
}
let code = await compilerCtx.fs.readFile(filePath);
if (typeof code !== 'string' && isRemoteUrl(compilerExe)) {
const url = getStencilModuleUrl(compilerExe, filePath);
code = await fetchModuleAsync(config.sys, compilerCtx.fs, packageVersions, url, filePath);
}
if (typeof code === 'string') {
const hydratedFlag = config.hydratedFlag;
if (hydratedFlag) {
const hydratedFlagHead = getHydratedFlagHead(hydratedFlag);
if (HYDRATED_CSS !== hydratedFlagHead) {
code = code.replace(HYDRATED_CSS, hydratedFlagHead);
if (hydratedFlag.name !== 'hydrated') {
code = code.replace(`.classList.add("hydrated")`, `.classList.add("${hydratedFlag.name}")`);
code = code.replace(`.classList.add('hydrated')`, `.classList.add('${hydratedFlag.name}')`);
code = code.replace(`.setAttribute("hydrated",`, `.setAttribute("${hydratedFlag.name}",`);
code = code.replace(`.setAttribute('hydrated',`, `.setAttribute('${hydratedFlag.name}',`);
}
}
} else {
code = code.replace(HYDRATED_CSS, '{}');
}
}
return code;
}
}
return null;
},
};
};
export const getStencilInternalModule = (config: d.ValidatedConfig, compilerExe: string, internalModule: string) => {
if (isRemoteUrl(compilerExe)) {
return normalizePath(
config.sys.getLocalModulePath({
rootDir: config.rootDir,
moduleId: '@stencil/core',
path: 'internal/' + internalModule,
}),
);
}
const compilerExeDir = dirname(compilerExe);
return normalizePath(join(compilerExeDir, '..', 'internal', internalModule));
};
export const getHydratedFlagHead = (h: d.HydratedFlag) => {
// {visibility:hidden}.hydrated{visibility:inherit}
let initial: string;
let hydrated: string;
if (!String(h.initialValue) || h.initialValue === '' || h.initialValue == null) {
initial = '';
} else {
initial = `{${h.property}:${h.initialValue}}`;
}
const selector = h.selector === 'attribute' ? `[${h.name}]` : `.${h.name}`;
if (!String(h.hydratedValue) || h.hydratedValue === '' || h.hydratedValue == null) {
hydrated = '';
} else {
hydrated = `${selector}{${h.property}:${h.hydratedValue}}`;
}
return initial + hydrated;
};
================================================
FILE: src/compiler/bundle/dev-module.ts
================================================
import { generatePreamble, join, relative } from '@utils';
import { basename, dirname } from 'path';
import { OutputOptions, rollup } from 'rollup';
import type * as d from '../../declarations';
import { BuildContext } from '../build/build-ctx';
import { getRollupOptions } from './bundle-output';
import { DEV_MODULE_CACHE_BUSTER, DEV_MODULE_DIR } from './constants';
export const compilerRequest = async (
config: d.ValidatedConfig,
compilerCtx: d.CompilerCtx,
data: d.CompilerRequest,
) => {
const results: d.CompilerRequestResponse = {
path: data.path,
nodeModuleId: null,
nodeModuleVersion: null,
nodeResolvedPath: null,
cachePath: null,
cacheHit: false,
content: '',
status: 404,
};
try {
const parsedUrl = parseDevModuleUrl(config, data.path);
Object.assign(results, parsedUrl);
if (parsedUrl.nodeModuleId) {
if (!parsedUrl.nodeModuleVersion) {
results.content = `/* invalid module version */`;
results.status = 400;
return results;
}
if (!parsedUrl.nodeResolvedPath) {
results.content = `/* invalid resolved path */`;
results.status = 400;
return results;
}
const useCache = await useDevModuleCache(config, parsedUrl.nodeResolvedPath);
let cachePath: string = null;
if (useCache) {
cachePath = getDevModuleCachePath(config, parsedUrl);
const cachedContent = await config.sys.readFile(cachePath);
if (typeof cachedContent === 'string') {
results.content = cachedContent;
results.cachePath = cachePath;
results.cacheHit = true;
results.status = 200;
return results;
}
}
await bundleDevModule(config, compilerCtx, parsedUrl, results);
if (results.status === 200 && useCache) {
results.cachePath = cachePath;
writeCachedFile(config, results);
}
} else {
results.content = `/* invalid dev module */`;
results.status = 400;
return results;
}
} catch (e: unknown) {
if (e) {
if (e instanceof Error && e.stack) {
results.content = `/*\n${e.stack}\n*/`;
} else {
results.content = `/*\n${e}\n*/`;
}
}
results.status = 500;
}
return results;
};
const bundleDevModule = async (
config: d.ValidatedConfig,
compilerCtx: d.CompilerCtx,
parsedUrl: ParsedDevModuleUrl,
results: d.CompilerRequestResponse,
) => {
const buildCtx = new BuildContext(config, compilerCtx);
try {
const inputOpts = getRollupOptions(config, compilerCtx, buildCtx, {
id: parsedUrl.nodeModuleId,
platform: 'client',
inputs: {
index: parsedUrl.nodeResolvedPath,
},
});
const rollupBuild = await rollup(inputOpts);
const outputOpts: OutputOptions = {
banner: generatePreamble(config),
format: 'es',
};
if (parsedUrl.nodeModuleId) {
const commentPath = relative(config.rootDir, parsedUrl.nodeResolvedPath);
outputOpts.intro = `/**\n * Dev Node Module: ${parsedUrl.nodeModuleId}, v${parsedUrl.nodeModuleVersion}\n * Entry: ${commentPath}\n * DEVELOPMENT PURPOSES ONLY!!\n */`;
inputOpts.input = parsedUrl.nodeResolvedPath;
}
const r = await rollupBuild.generate(outputOpts);
if (buildCtx.hasError) {
results.status = 500;
results.content = `console.error(${JSON.stringify(buildCtx.diagnostics)})`;
} else if (r && r.output && r.output.length > 0) {
results.content = r.output[0].code;
results.status = 200;
}
} catch (e) {
results.status = 500;
const errorMsg = e instanceof Error ? e.stack : e + '';
results.content = `console.error(${JSON.stringify(errorMsg)})`;
}
};
const useDevModuleCache = async (config: d.ValidatedConfig, p: string) => {
if (config.enableCache) {
for (let i = 0; i < 10; i++) {
const n = basename(p);
if (n === 'node_modules') {
return true;
}
const isSymbolicLink = await config.sys.isSymbolicLink(p);
if (isSymbolicLink) {
return false;
}
p = dirname(p);
}
}
return false;
};
const writeCachedFile = async (config: d.ValidatedConfig, results: d.CompilerRequestResponse) => {
try {
await config.sys.createDir(config.cacheDir);
config.sys.writeFile(results.cachePath, results.content);
} catch (e) {
console.error(e);
}
};
const parseDevModuleUrl = (config: d.ValidatedConfig, u: string) => {
const parsedUrl: ParsedDevModuleUrl = {
nodeModuleId: null,
nodeModuleVersion: null,
nodeResolvedPath: null,
};
if (u && u.includes(DEV_MODULE_DIR) && u.endsWith('.js')) {
const url = new URL(u, 'https://stenciljs.com');
let reqPath = basename(url.pathname);
reqPath = reqPath.substring(0, reqPath.length - 3);
const splt = reqPath.split('@');
if (splt.length === 2) {
parsedUrl.nodeModuleId = decodeURIComponent(splt[0]);
parsedUrl.nodeModuleVersion = decodeURIComponent(splt[1]);
parsedUrl.nodeResolvedPath = url.searchParams.get('p');
if (parsedUrl.nodeResolvedPath) {
parsedUrl.nodeResolvedPath = decodeURIComponent(parsedUrl.nodeResolvedPath);
parsedUrl.nodeResolvedPath = join(config.rootDir, parsedUrl.nodeResolvedPath);
}
}
}
return parsedUrl;
};
const getDevModuleCachePath = (config: d.ValidatedConfig, parsedUrl: ParsedDevModuleUrl) => {
return join(
config.cacheDir,
`dev_module_${parsedUrl.nodeModuleId}_${parsedUrl.nodeModuleVersion}_${DEV_MODULE_CACHE_BUSTER}.log`,
);
};
interface ParsedDevModuleUrl {
nodeModuleId: string;
nodeModuleVersion: string;
nodeResolvedPath: string;
}
================================================
FILE: src/compiler/bundle/dev-node-module-resolve.ts
================================================
import { join, relative } from '@utils';
import { basename, dirname } from 'path';
import { ResolveIdResult } from 'rollup';
import type * as d from '../../declarations';
import { InMemoryFileSystem } from '../sys/in-memory-fs';
import { DEV_MODULE_DIR } from './constants';
export const devNodeModuleResolveId = async (
config: d.ValidatedConfig,
inMemoryFs: InMemoryFileSystem,
resolvedId: ResolveIdResult,
importee: string,
) => {
if (!shouldCheckDevModule(resolvedId, importee)) {
return resolvedId;
}
if (typeof resolvedId === 'string' || !resolvedId) {
return resolvedId;
}
const resolvedPath = resolvedId.id;
const pkgPath = getPackageJsonPath(resolvedPath, importee);
if (!pkgPath) {
return resolvedId;
}
const pkgJsonStr = await inMemoryFs.readFile(pkgPath);
if (!pkgJsonStr) {
return resolvedId;
}
let pkgJsonData: d.PackageJsonData;
try {
pkgJsonData = JSON.parse(pkgJsonStr);
} catch (e) {}
if (!pkgJsonData || !pkgJsonData.version) {
return resolvedId;
}
resolvedId.id = serializeDevNodeModuleUrl(config, pkgJsonData.name, pkgJsonData.version, resolvedPath);
resolvedId.external = true;
return resolvedId;
};
const shouldCheckDevModule = (resolvedId: ResolveIdResult, importee: string) =>
resolvedId &&
importee &&
typeof resolvedId !== 'string' &&
resolvedId.id &&
resolvedId.id.includes('node_modules') &&
(resolvedId.id.endsWith('.js') || resolvedId.id.endsWith('.mjs')) &&
!resolvedId.external &&
!importee.startsWith('.') &&
!importee.startsWith('/');
const getPackageJsonPath = (resolvedPath: string, importee: string): string => {
let currentPath = resolvedPath;
for (let i = 0; i < 10; i++) {
currentPath = dirname(currentPath);
const aBasename = basename(currentPath);
const upDir = dirname(currentPath);
const bBasename = basename(upDir);
if (aBasename === importee && bBasename === 'node_modules') {
return join(currentPath, 'package.json');
}
}
return null;
};
const serializeDevNodeModuleUrl = (
config: d.ValidatedConfig,
moduleId: string,
moduleVersion: string,
resolvedPath: string,
) => {
resolvedPath = relative(config.rootDir, resolvedPath);
let id = `/${DEV_MODULE_DIR}/`;
id += encodeURIComponent(moduleId) + '@';
id += encodeURIComponent(moduleVersion) + '.js';
id += '?p=' + encodeURIComponent(resolvedPath);
return id;
};
================================================
FILE: src/compiler/bundle/entry-alias-ids.ts
================================================
export const STENCIL_CORE_ID = '@stencil/core';
export const STENCIL_INTERNAL_ID = '@stencil/core/internal';
export const STENCIL_APP_DATA_ID = '@stencil/core/internal/app-data';
export const STENCIL_APP_GLOBALS_ID = '@stencil/core/internal/app-globals';
export const STENCIL_HYDRATE_FACTORY_ID = '@stencil/core/hydrate-factory';
export const STENCIL_INTERNAL_CLIENT_ID = '@stencil/core/internal/client';
export const STENCIL_INTERNAL_CLIENT_PATCH_BROWSER_ID = '@stencil/core/internal/client/patch-browser';
export const STENCIL_INTERNAL_HYDRATE_ID = '@stencil/core/internal/hydrate';
export const STENCIL_MOCK_DOC_ID = '@stencil/core/mock-doc';
export const STENCIL_JSX_RUNTIME_ID = '@stencil/core/jsx-runtime';
export const STENCIL_JSX_DEV_RUNTIME_ID = '@stencil/core/jsx-dev-runtime';
export const APP_DATA_CONDITIONAL = '?app-data=conditional';
export const LAZY_BROWSER_ENTRY_ID = '@lazy-browser-entrypoint' + APP_DATA_CONDITIONAL;
export const LAZY_EXTERNAL_ENTRY_ID = '@lazy-external-entrypoint' + APP_DATA_CONDITIONAL;
export const USER_INDEX_ENTRY_ID = '@user-index-entrypoint';
================================================
FILE: src/compiler/bundle/ext-format-plugin.ts
================================================
import { createJsVarName, normalizeFsPathQuery } from '@utils';
import { basename } from 'path';
import type { Plugin, TransformPluginContext, TransformResult } from 'rollup';
import type * as d from '../../declarations';
export const extFormatPlugin = (config: d.ValidatedConfig): Plugin => {
return {
name: 'extFormatPlugin',
transform(code: string, importPath: string): TransformResult {
if (/\0/.test(importPath)) {
return null;
}
const { ext, filePath, format } = normalizeFsPathQuery(importPath);
// ?format= param takes precedence before file extension
switch (format) {
case 'url':
return { code: formatUrl(config, this, code, filePath, ext), map: null };
case 'text':
return { code: formatText(code, filePath), map: null };
}
// didn't provide a ?format= param
// check if it's a known extension we should format
if (ext != null && FORMAT_TEXT_EXTS.includes(ext)) {
return { code: formatText(code, filePath), map: null };
}
if (ext != null && FORMAT_URL_MIME[ext]) {
return { code: formatUrl(config, this, code, filePath, ext), map: null };
}
return null;
},
};
};
const FORMAT_TEXT_EXTS = ['txt', 'frag', 'vert'];
const FORMAT_URL_MIME: any = {
svg: 'image/svg+xml',
};
const DATAURL_MAX_IMAGE_SIZE = 4 * 1024; // 4KiB
const formatText = (code: string, filePath: string) => {
const varName = createJsVarName(basename(filePath));
return `const ${varName} = ${JSON.stringify(code)};export default ${varName};`;
};
const formatUrl = (
config: d.ValidatedConfig,
pluginCtx: TransformPluginContext,
code: string,
filePath: string,
ext: string | null,
) => {
const mime = ext != null ? FORMAT_URL_MIME[ext] : null;
if (!mime) {
pluginCtx.warn(`Unsupported url format for "${ext}" extension.`);
return formatText('', filePath);
}
const varName = createJsVarName(basename(filePath));
const base64 = config.sys.encodeToBase64(code);
if (config.devMode && base64.length > DATAURL_MAX_IMAGE_SIZE) {
pluginCtx.warn(`Importing large files will bloat your bundle size, please use external assets instead.`);
}
return `const ${varName} = 'data:${mime};base64,${base64}';export default ${varName};`;
};
================================================
FILE: src/compiler/bundle/ext-transforms-plugin.ts
================================================
import { hasError, isOutputTargetDistCollection, join, mergeIntoWith, normalizeFsPath, relative } from '@utils';
import type { Plugin } from 'rollup';
import type * as d from '../../declarations';
import { runPluginTransformsEsmImports } from '../plugin/plugin';
import { getScopeId } from '../style/scope-css';
import { parseImportPath } from '../transformers/stencil-import-path';
/**
* This keeps a map of all the component styles we've seen already so we can create
* a correct state of all styles when we're doing a rebuild. This map helps by
* storing the state of all styles as follows, e.g.:
*
* ```
* {
* 'cmp-a-$': {
* '/path/to/project/cmp-a.scss': 'button{color:red}',
* '/path/to/project/cmp-a.md.scss': 'button{color:blue}'
* }
* ```
*
* Whenever one of the files change, we can propagate a correct concatenated
* version of all styles to the browser by setting `buildCtx.stylesUpdated`.
*/
type ComponentStyleMap = Map;
const allCmpStyles = new Map();
/**
* A Rollup plugin which bundles up some transformation of CSS imports as well
* as writing some files to disk for the `DIST_COLLECTION` output target.
*
* @param config a user-supplied configuration
* @param compilerCtx the current compiler context
* @param buildCtx the current build context
* @returns a Rollup plugin which carries out the necessary work
*/
export const extTransformsPlugin = (
config: d.ValidatedConfig,
compilerCtx: d.CompilerCtx,
buildCtx: d.BuildCtx,
): Plugin => {
return {
name: 'extTransformsPlugin',
/**
* A custom function targeting the `transform` build hook in Rollup. See here for details:
* https://rollupjs.org/guide/en/#transform
*
* Here we are ignoring the first argument (which contains the module's source code) and
* only looking at the `id` argument. We use that `id` to get information about the module
* in question from disk ourselves so that we can then do some transformations on it.
*
* @param _ an unused parameter (normally the code for a given module)
* @param id the id of a module
* @returns metadata for Rollup or null if no transformation should be done
*/
async transform(_, id) {
if (/\0/.test(id)) {
return null;
}
/**
* Make sure compiler context has a registered worker. The interface suggests that it
* potentially can be undefined, therefore check for it here.
*/
if (!compilerCtx.worker) {
return null;
}
// The `id` here was possibly previously updated using
// `serializeImportPath` to annotate the filepath with various metadata
// serialized to query-params. If that was done for this particular `id`
// then the `data` prop will not be null.
const { data } = parseImportPath(id);
if (data != null) {
let cmpStyles: ComponentStyleMap | undefined = undefined;
let cmp: d.ComponentCompilerMeta | undefined = undefined;
const filePath = normalizeFsPath(id);
const code = await compilerCtx.fs.readFile(filePath);
if (typeof code !== 'string') {
return null;
}
/**
* add file to watch list if it is outside of the `srcDir` config path
*/
if (config.watch && (id.startsWith('/') || id.startsWith('.')) && !id.startsWith(config.srcDir)) {
compilerCtx.addWatchFile(id.split('?')[0]);
}
const pluginTransforms = await runPluginTransformsEsmImports(config, compilerCtx, buildCtx, code, filePath);
if (data.tag) {
cmp = buildCtx.components.find((c) => c.tagName === data.tag);
const moduleFile = cmp && !cmp.isCollectionDependency && compilerCtx.moduleMap.get(cmp.sourceFilePath);
if (moduleFile) {
const collectionDirs = config.outputTargets.filter(isOutputTargetDistCollection);
const relPath = relative(config.srcDir, pluginTransforms.id);
// If we found a `moduleFile` in the module map above then we
// should write the transformed CSS file (found in the return value
// of `runPluginTransformsEsmImports`, above) to disk.
await Promise.all(
collectionDirs.map(async (outputTarget) => {
const collectionPath = join(outputTarget.collectionDir, relPath);
await compilerCtx.fs.writeFile(collectionPath, pluginTransforms.code);
}),
);
}
/**
* initiate map for component styles
*/
const scopeId = getScopeId(data.tag, data.mode);
if (!allCmpStyles.has(scopeId)) {
allCmpStyles.set(scopeId, new Map());
}
cmpStyles = allCmpStyles.get(scopeId);
}
const cssTransformResults = await compilerCtx.worker.transformCssToEsm({
file: pluginTransforms.id,
input: pluginTransforms.code,
tag: data.tag,
tags: buildCtx.components.map((c) => c.tagName),
addTagTransformers: !!buildCtx.config.extras.additionalTagTransformers,
encapsulation: data.encapsulation,
mode: data.mode,
sourceMap: config.sourceMap,
minify: config.minifyCss,
autoprefixer: config.autoprefixCss,
docs: config.buildDocs,
});
/**
* persist component styles for transformed stylesheet
*/
if (cmpStyles) {
cmpStyles.set(filePath, cssTransformResults.styleText);
}
// Set style docs
if (cmp) {
cmp.styleDocs ||= [];
mergeIntoWith(cmp.styleDocs, cssTransformResults.styleDocs, (docs) => `${docs.name},${docs.mode}`);
}
// Track dependencies
for (const dep of pluginTransforms.dependencies) {
this.addWatchFile(dep);
compilerCtx.addWatchFile(dep);
}
buildCtx.diagnostics.push(...pluginTransforms.diagnostics);
buildCtx.diagnostics.push(...cssTransformResults.diagnostics);
const didError = hasError(cssTransformResults.diagnostics) || hasError(pluginTransforms.diagnostics);
if (didError) {
this.error('Plugin CSS transform error');
}
const hasUpdatedStyle = buildCtx.stylesUpdated.some((s) => {
return s.styleTag === data.tag && s.styleMode === data.mode && s.styleText === cssTransformResults.styleText;
});
/**
* if the style has updated, compose all styles for the component
*/
if (!hasUpdatedStyle && data.tag && data.mode) {
const externalStyles = cmp?.styles?.[0]?.externalStyles;
/**
* if component has external styles, use a list to keep the order to which
* styles are applied.
*/
const styleText = cmpStyles
? externalStyles
? /**
* attempt to find the original `filePath` key through `originalComponentPath`
* and `absolutePath` as path can differ based on how Stencil is installed
* e.g. through `npm link` or `npm install`
*/
externalStyles
.map((es) => cmpStyles.get(es.originalComponentPath) || cmpStyles.get(es.absolutePath))
.join('\n')
: /**
* if `externalStyles` is not defined, then created the style text in the
* order of which the styles were compiled.
*/
[...cmpStyles.values()].join('\n')
: /**
* if `cmpStyles` is not defined, then use the style text from the transform
* as it is not connected to a component.
*/
cssTransformResults.styleText;
buildCtx.stylesUpdated.push({
styleTag: data.tag,
styleMode: data.mode,
styleText,
});
}
return {
code: cssTransformResults.output,
map: cssTransformResults.map,
moduleSideEffects: false,
};
}
return null;
},
};
};
================================================
FILE: src/compiler/bundle/file-load-plugin.ts
================================================
import { isDtsFile, normalizeFsPath } from '@utils';
import type { Plugin } from 'rollup';
import { InMemoryFileSystem } from '../sys/in-memory-fs';
export const fileLoadPlugin = (fs: InMemoryFileSystem): Plugin => {
return {
name: 'fileLoadPlugin',
load(id) {
const fsFilePath = normalizeFsPath(id);
if (isDtsFile(fsFilePath)) {
return '';
}
return fs.readFile(fsFilePath);
},
};
};
================================================
FILE: src/compiler/bundle/loader-plugin.ts
================================================
import type { LoadResult, Plugin, ResolveIdResult } from 'rollup';
/**
* Rollup plugin that aids in resolving the entry points (1 or more files) for a Stencil project. For example, a project
* using the `dist-custom-elements` output target may have a single 'entry point' for each file containing a component.
* Each of those files will be independently resolved and loaded by this plugin for further processing by Rollup later
* in the bundling process.
*
* @param entries the Stencil project files to process. It should be noted that the keys in this object may not
* necessarily be an absolute or relative path to a file, but may be a Rollup Virtual Module (which begin with \0).
* @returns the rollup plugin that loads and process a Stencil project's entry points
*/
export const loaderPlugin = (entries: { [id: string]: string } = {}): Plugin => {
return {
name: 'stencilLoaderPlugin',
/**
* A rollup build hook for resolving the imports of individual Stencil project files. This hook only resolves
* modules that are contained in the plugin's `entries` argument. [Source](https://rollupjs.org/guide/en/#resolveid)
* @param id the importee to resolve
* @returns a string that resolves an import to some id, null otherwise
*/
resolveId(id: string): ResolveIdResult {
if (id in entries) {
return {
id,
};
}
return null;
},
/**
* A rollup build hook for loading individual Stencil project files [Source](https://rollupjs.org/guide/en/#load)
* @param id the path of the module to load. It should be noted that the keys in this object may not necessarily
* be an absolute or relative path to a file, but may be a Rollup Virtual Module.
* @returns the module matched, null otherwise
*/
load(id: string): LoadResult {
if (id in entries) {
return entries[id];
}
return null;
},
};
};
================================================
FILE: src/compiler/bundle/plugin-helper.ts
================================================
import { buildError, relative } from '@utils';
import type * as d from '../../declarations';
import type { BundlePlatform } from './bundle-interface';
export const pluginHelper = (config: d.ValidatedConfig, builtCtx: d.BuildCtx, platform: BundlePlatform) => {
return {
name: 'pluginHelper',
resolveId(importee: string, importer: string): null {
if (/\0/.test(importee)) {
// ignore IDs with null character, these belong to other plugins
return null;
}
if (importee.endsWith('/')) {
importee = importee.slice(0, -1);
}
if (builtIns.has(importee)) {
let fromMsg = '';
if (importer) {
fromMsg = ` from ${relative(config.rootDir, importer)}`;
}
const diagnostic = buildError(builtCtx.diagnostics);
diagnostic.header = `Node Polyfills Required`;
diagnostic.messageText = `For the import "${importee}" to be bundled${fromMsg}, ensure the "rollup-plugin-node-polyfills" plugin is installed and added to the stencil config plugins (${platform}). Please see the bundling docs for more information.
Further information: https://stenciljs.com/docs/module-bundling`;
}
return null;
},
};
};
const builtIns = new Set([
'child_process',
'cluster',
'dgram',
'dns',
'module',
'net',
'readline',
'repl',
'tls',
'assert',
'console',
'constants',
'domain',
'events',
'path',
'punycode',
'querystring',
'_stream_duplex',
'_stream_passthrough',
'_stream_readable',
'_stream_writable',
'_stream_transform',
'string_decoder',
'sys',
'tty',
'crypto',
'fs',
'Buffer',
'buffer',
'global',
'http',
'https',
'os',
'process',
'stream',
'timers',
'url',
'util',
'vm',
'zlib',
]);
================================================
FILE: src/compiler/bundle/server-plugin.ts
================================================
import { isOutputTargetHydrate, isString, normalizeFsPath } from '@utils';
import { isAbsolute } from 'path';
import type { Plugin } from 'rollup';
import type * as d from '../../declarations';
import type { BundlePlatform } from './bundle-interface';
export const serverPlugin = (config: d.ValidatedConfig, platform: BundlePlatform): Plugin => {
const isHydrateBundle = platform === 'hydrate';
const serverVarid = `@removed-server-code`;
const isServerOnlyModule = (id: string) => {
if (isString(id)) {
id = normalizeFsPath(id);
return id.includes('.server/') || id.endsWith('.server');
}
return false;
};
const externals = isHydrateBundle
? config.outputTargets.filter(isOutputTargetHydrate).flatMap((o) => o.external)
: [];
return {
name: 'serverPlugin',
resolveId(id, importer) {
if (id === serverVarid) {
return id;
}
if (isHydrateBundle) {
if (externals.includes(id)) {
// don't attempt to bundle node builtins for the hydrate bundle
return {
id,
external: true,
};
}
if (isServerOnlyModule(importer) && !id.startsWith('.') && !isAbsolute(id)) {
// do not bundle if the importer is a server-only module
// and the module it is importing is a node module
return {
id,
external: true,
};
}
} else {
if (isServerOnlyModule(id)) {
// any path that has .server in it shouldn't actually
// be bundled in the web build, only the hydrate build
return serverVarid;
}
}
return null;
},
load(id) {
if (id === serverVarid) {
return {
code: 'export default {};',
syntheticNamedExports: true,
};
}
return null;
},
};
};
================================================
FILE: src/compiler/bundle/test/app-data-plugin.spec.ts
================================================
import * as d from '@stencil/core/declarations';
import { mockValidatedConfig } from '@stencil/core/testing';
import MagicString from 'magic-string';
import { appendBuildConditionals } from '../app-data-plugin';
function setup() {
const config = mockValidatedConfig();
const magicString = new MagicString('');
return { config, magicString };
}
describe('app data plugin', () => {
it('should include the fsNamespace in the appended BUILD constant', () => {
const { config, magicString } = setup();
appendBuildConditionals(config, {}, magicString);
expect(magicString.toString().includes(`export const BUILD = /* ${config.fsNamespace} */`)).toBe(true);
});
it.each([true, false])('should include hydratedAttribute when %p', (hydratedAttribute) => {
const conditionals: d.BuildConditionals = {
hydratedAttribute,
};
const { config, magicString } = setup();
appendBuildConditionals(config, conditionals, magicString);
expect(magicString.toString().includes(`hydratedAttribute: ${String(hydratedAttribute)}`)).toBe(true);
});
it.each([true, false])('should include hydratedClass when %p', (hydratedClass) => {
const conditionals: d.BuildConditionals = {
hydratedClass,
};
const { config, magicString } = setup();
appendBuildConditionals(config, conditionals, magicString);
expect(magicString.toString().includes(`hydratedClass: ${String(hydratedClass)}`)).toBe(true);
});
it('should append hydratedSelectorName', () => {
const conditionals: d.BuildConditionals = {
hydratedSelectorName: 'boop',
};
const { config, magicString } = setup();
appendBuildConditionals(config, conditionals, magicString);
expect(magicString.toString().includes('hydratedSelectorName: "boop"')).toBe(true);
});
});
================================================
FILE: src/compiler/bundle/test/core-resolve-plugin.spec.ts
================================================
import { mockCompilerCtx, mockValidatedConfig } from '@stencil/core/testing';
import { createSystem } from '../../../compiler/sys/stencil-sys';
import type * as d from '../../../declarations';
import { coreResolvePlugin, getHydratedFlagHead, getStencilInternalModule } from '../core-resolve-plugin';
import { APP_DATA_CONDITIONAL, STENCIL_JSX_RUNTIME_ID } from '../entry-alias-ids';
describe('core resolve plugin', () => {
const config: d.ValidatedConfig = mockValidatedConfig({
rootDir: '/',
sys: createSystem(),
});
it('http localhost with port url path', () => {
const compilerExe = 'http://localhost:3333/@stencil/core/compiler/stencil.js?v=1.2.3';
const internalModule = 'hydrate/index.js';
const m = getStencilInternalModule(config, compilerExe, internalModule);
expect(m).toBe('/node_modules/@stencil/core/internal/hydrate/index.js');
});
it('node path', () => {
const compilerExe = '/Users/me/node_modules/stencil/compiler/stencil.js';
const internalModule = 'client/index.js';
const m = getStencilInternalModule(config, compilerExe, internalModule);
expect(m).toBe('/Users/me/node_modules/stencil/internal/client/index.js');
});
it('should not set initialValue', () => {
const o = getHydratedFlagHead({
name: 'yup',
selector: 'class',
property: 'display',
initialValue: null,
hydratedValue: 'block',
});
expect(o).toBe(`.yup{display:block}`);
});
it('should not set hydratedValue', () => {
const o = getHydratedFlagHead({
name: 'yup',
selector: 'class',
property: 'display',
initialValue: 'none',
hydratedValue: null,
});
expect(o).toBe(`{display:none}`);
});
it('should set class selector', () => {
const o = getHydratedFlagHead({
name: 'yup',
selector: 'class',
property: 'display',
initialValue: 'none',
hydratedValue: 'block',
});
expect(o).toBe(`{display:none}.yup{display:block}`);
});
it('should set attribute selector', () => {
const o = getHydratedFlagHead({
name: 'yup',
selector: 'attribute',
property: 'display',
initialValue: 'none',
hydratedValue: 'block',
});
expect(o).toBe(`{display:none}[yup]{display:block}`);
});
describe('jsx-runtime resolution', () => {
it('should resolve jsx-runtime to same path as @stencil/core for lazy builds', () => {
const compilerCtx = mockCompilerCtx(config);
const plugin = coreResolvePlugin(config, compilerCtx, 'client', false, true);
const resolved = (plugin.resolveId as Function)(STENCIL_JSX_RUNTIME_ID);
expect(resolved).toContain('internal/client/index.js');
expect(resolved).toContain(APP_DATA_CONDITIONAL);
});
});
});
================================================
FILE: src/compiler/bundle/test/ext-transforms-plugin.spec.ts
================================================
import { mockBuildCtx, mockCompilerCtx, mockModule, mockValidatedConfig } from '@stencil/core/testing';
import { normalizePath } from '@utils';
import * as importPathLib from '../../transformers/stencil-import-path';
import { stubComponentCompilerMeta } from '../../types/tests/ComponentCompilerMeta.stub';
import { BundleOptions } from '../bundle-interface';
import { extTransformsPlugin } from '../ext-transforms-plugin';
describe('extTransformsPlugin', () => {
function setup(bundleOptsOverrides: Partial = {}) {
const config = mockValidatedConfig({
plugins: [],
outputTargets: [
{
type: 'dist-collection',
dir: 'dist/',
collectionDir: 'dist/collectionDir',
},
],
srcDir: '/some/stubbed/path',
});
const compilerCtx = mockCompilerCtx(config);
const buildCtx = mockBuildCtx(config, compilerCtx);
const compilerComponentMeta = stubComponentCompilerMeta({
tagName: 'my-component',
componentClassName: 'MyComponent',
});
buildCtx.components = [compilerComponentMeta];
compilerCtx.moduleMap.set(
compilerComponentMeta.sourceFilePath,
mockModule({
cmps: [compilerComponentMeta],
}),
);
const bundleOpts: BundleOptions = {
id: 'test-bundle',
platform: 'client',
inputs: {},
...bundleOptsOverrides,
};
const cssText = ':host { text: pink; }';
// mock out the read for our CSS
jest.spyOn(compilerCtx.fs, 'readFile').mockResolvedValue(cssText);
// mock out compilerCtx.worker.transformCssToEsm because 1) we want to
// test what arguments are passed to it and 2) calling it un-mocked causes
// the infamous autoprefixer-spew-issue :(
const transformCssToEsmSpy = jest.spyOn(compilerCtx.worker, 'transformCssToEsm').mockResolvedValue({
styleText: cssText,
output: cssText,
map: null,
diagnostics: [],
imports: [],
defaultVarName: 'foo',
styleDocs: [],
});
const writeFileSpy = jest.spyOn(compilerCtx.fs, 'writeFile');
return {
plugin: extTransformsPlugin(config, compilerCtx, buildCtx),
config,
compilerCtx,
buildCtx,
bundleOpts,
writeFileSpy,
transformCssToEsmSpy,
cssText,
};
}
describe('transform function', () => {
it('should set name', () => {
expect(setup().plugin.name).toBe('extTransformsPlugin');
});
it('should return early if no data can be gleaned from the id', async () => {
const { plugin } = setup();
// @ts-ignore we're testing something which shouldn't normally happen,
// but might if an argument of the wrong type were passed as `id`
const parseSpy = jest.spyOn(importPathLib, 'parseImportPath').mockReturnValue({ data: null });
// @ts-ignore the Rollup plugins expect to be called in a Rollup context
expect(await plugin.transform('asdf', 'foo.css')).toBe(null);
parseSpy.mockRestore();
});
it('should write CSS files if associated with a tag', async () => {
const { plugin, writeFileSpy } = setup();
// @ts-ignore the Rollup plugins expect to be called in a Rollup context
await plugin.transform('asdf', '/some/stubbed/path/foo.css?tag=my-component');
const [path, css] = writeFileSpy.mock.calls[0];
expect(normalizePath(path)).toBe('./dist/collectionDir/foo.css');
expect(css).toBe(':host { text: pink; }');
});
});
});
================================================
FILE: src/compiler/bundle/typescript-plugin.ts
================================================
import { isDtsFile, isString, normalizeFsPath } from '@utils';
import { basename, isAbsolute } from 'path';
import type { LoadResult, Plugin, TransformResult } from 'rollup';
import ts from 'typescript';
import type * as d from '../../declarations';
import { tsResolveModuleName } from '../sys/typescript/typescript-resolve-module';
import { getModule } from '../transpile/transpiled-module';
import type { BundleOptions } from './bundle-interface';
/**
* Rollup plugin that aids in resolving the TypeScript files and performing the transpilation step.
* @param compilerCtx the current compiler context
* @param bundleOpts Rollup bundling options to apply during TypeScript compilation
* @param config the Stencil configuration for the project
* @returns the rollup plugin for handling TypeScript files.
*/
export const typescriptPlugin = (
compilerCtx: d.CompilerCtx,
bundleOpts: BundleOptions,
config: d.ValidatedConfig,
): Plugin => {
return {
name: `${bundleOpts.id}TypescriptPlugin`,
/**
* A rollup build hook for loading TypeScript files and their associated source maps (if they exist).
* [Source](https://rollupjs.org/guide/en/#load)
* @param id the path of the file to load
* @returns the module matched (with its sourcemap if it exists), null otherwise
*/
load(id: string): LoadResult {
if (isAbsolute(id)) {
const fsFilePath = normalizeFsPath(id);
const module = getModule(compilerCtx, fsFilePath);
if (module) {
if (!module.sourceMapFileText) {
return { code: module.staticSourceFileText, map: null };
}
const sourceMap: d.SourceMap = JSON.parse(module.sourceMapFileText);
sourceMap.sources = sourceMap.sources.map((src) => basename(src));
return { code: module.staticSourceFileText, map: sourceMap };
}
}
return null;
},
/**
* Performs TypeScript compilation/transpilation, including applying any transformations against the Abstract Syntax
* Tree (AST) specific to stencil
* @param _code the code to modify, unused
* @param id module's identifier
* @returns the transpiled code, with its associated sourcemap. null otherwise
*/
transform(_code: string, id: string): TransformResult {
if (isAbsolute(id)) {
const fsFilePath = normalizeFsPath(id);
const mod = getModule(compilerCtx, fsFilePath);
if (mod?.cmps) {
const tsResult = ts.transpileModule(mod.staticSourceFileText, {
compilerOptions: config.tsCompilerOptions,
fileName: mod.sourceFilePath,
transformers: {
before: bundleOpts.customBeforeTransformers ?? [],
},
});
const sourceMap: d.SourceMap = tsResult.sourceMapText ? JSON.parse(tsResult.sourceMapText) : null;
return { code: tsResult.outputText, map: sourceMap };
}
}
return null;
},
};
};
export const resolveIdWithTypeScript = (config: d.ValidatedConfig, compilerCtx: d.CompilerCtx): Plugin => {
return {
name: `resolveIdWithTypeScript`,
async resolveId(importee, importer) {
if (/\0/.test(importee) || !isString(importer)) {
return null;
}
const tsResolved = tsResolveModuleName(config, compilerCtx, importee, importer);
if (tsResolved && tsResolved.resolvedModule) {
// this is probably a .d.ts file for whatever reason in how TS resolves this
// use this resolved file as the "importer"
const tsResolvedPath = tsResolved.resolvedModule.resolvedFileName;
if (isString(tsResolvedPath) && !isDtsFile(tsResolvedPath)) {
return tsResolvedPath;
}
}
return null;
},
};
};
================================================
FILE: src/compiler/bundle/user-index-plugin.ts
================================================
import { join } from '@utils';
import type { Plugin } from 'rollup';
import type * as d from '../../declarations';
import { USER_INDEX_ENTRY_ID } from './entry-alias-ids';
export const userIndexPlugin = (config: d.ValidatedConfig, compilerCtx: d.CompilerCtx): Plugin => {
return {
name: 'userIndexPlugin',
async resolveId(importee) {
if (importee === USER_INDEX_ENTRY_ID) {
const usersIndexJsPath = join(config.srcDir, 'index.ts');
const hasUserIndex = await compilerCtx.fs.access(usersIndexJsPath);
if (hasUserIndex) {
return usersIndexJsPath;
}
return importee;
}
return null;
},
async load(id) {
if (id === USER_INDEX_ENTRY_ID) {
return `//! Autogenerated index`;
}
return null;
},
};
};
================================================
FILE: src/compiler/bundle/worker-plugin.ts
================================================
import { generatePreamble, hasError, normalizeFsPath } from '@utils';
import type { Plugin, PluginContext, TransformResult } from 'rollup';
import type * as d from '../../declarations';
import type { BundlePlatform } from './bundle-interface';
import { optimizeModule } from '../optimize/optimize-module';
import { bundleOutput } from './bundle-output';
import { STENCIL_INTERNAL_ID } from './entry-alias-ids';
export const workerPlugin = (
config: d.ValidatedConfig,
compilerCtx: d.CompilerCtx,
buildCtx: d.BuildCtx,
platform: BundlePlatform,
inlineWorkers: boolean,
): Plugin => {
if (platform === 'worker' || platform === 'hydrate') {
return {
name: 'workerPlugin',
transform(_, id) {
if (id.endsWith('?worker') || id.endsWith('?worker-inline')) {
return getMockedWorkerMain();
}
return null;
},
};
}
const workersMap = new Map();
return {
name: 'workerPlugin',
buildStart() {
workersMap.clear();
},
resolveId(id) {
if (id === WORKER_HELPER_ID) {
return {
id,
moduleSideEffects: false,
};
}
return null;
},
load(id) {
if (id === WORKER_HELPER_ID) {
return WORKER_HELPERS;
}
return null;
},
async transform(_, id): Promise {
if (/\0/.test(id)) {
return null;
}
// Canonical worker path
if (id.endsWith('?worker')) {
const workerEntryPath = normalizeFsPath(id);
const workerName = getWorkerName(workerEntryPath);
const { code, dependencies, workerMsgId } = await getWorker(
config,
compilerCtx,
buildCtx,
this,
workersMap,
workerEntryPath,
);
const referenceId = this.emitFile({
type: 'asset',
source: code,
name: workerName + '.js',
});
dependencies.forEach((id) => this.addWatchFile(id));
return {
code: getWorkerMain(referenceId, workerName, workerMsgId),
moduleSideEffects: false,
};
} else if (id.endsWith('?worker-inline')) {
const workerEntryPath = normalizeFsPath(id);
const workerName = getWorkerName(workerEntryPath);
const { code, dependencies, workerMsgId } = await getWorker(
config,
compilerCtx,
buildCtx,
this,
workersMap,
workerEntryPath,
);
const referenceId = this.emitFile({
type: 'asset',
source: code,
name: workerName + '.js',
});
dependencies.forEach((id) => this.addWatchFile(id));
return {
code: getInlineWorker(referenceId, workerName, workerMsgId),
moduleSideEffects: false,
};
}
// Proxy worker path
const workerEntryPath = getWorkerEntryPath(id);
if (workerEntryPath != null) {
const worker = await getWorker(config, compilerCtx, buildCtx, this, workersMap, workerEntryPath);
if (worker) {
if (inlineWorkers) {
return {
code: getInlineWorkerProxy(workerEntryPath, worker.workerMsgId, worker.exports),
moduleSideEffects: false,
};
} else {
return {
code: getWorkerProxy(workerEntryPath, worker.exports),
moduleSideEffects: false,
};
}
}
}
return null;
},
};
};
const getWorkerEntryPath = (id: string) => {
if (WORKER_SUFFIX.some((p) => id.endsWith(p))) {
return normalizeFsPath(id);
}
return null;
};
interface WorkerMeta {
code: string;
workerMsgId: string;
exports: string[];
dependencies: string[];
}
const getWorker = async (
config: d.ValidatedConfig,
compilerCtx: d.CompilerCtx,
buildCtx: d.BuildCtx,
ctx: PluginContext,
workersMap: Map,
workerEntryPath: string,
): Promise => {
let worker = workersMap.get(workerEntryPath);
if (!worker) {
worker = await buildWorker(config, compilerCtx, buildCtx, ctx, workerEntryPath);
workersMap.set(workerEntryPath, worker);
}
return worker;
};
const getWorkerName = (id: string) => {
const parts = id.split('/').filter((i) => !i.includes('index'));
id = parts[parts.length - 1];
return id.replace('.tsx', '').replace('.ts', '');
};
const buildWorker = async (
config: d.ValidatedConfig,
compilerCtx: d.CompilerCtx,
buildCtx: d.BuildCtx,
ctx: PluginContext,
workerEntryPath: string,
) => {
const workerName = getWorkerName(workerEntryPath);
const workerMsgId = `stencil.${workerName}`;
const build = await bundleOutput(config, compilerCtx, buildCtx, {
platform: 'worker',
id: workerName,
inputs: {
[workerName]: workerEntryPath,
},
inlineDynamicImports: true,
});
if (build) {
// Generate commonjs output so we can intercept exports at runtime
const output = await build.generate({
format: 'commonjs',
banner: `${generatePreamble(config)}\n(()=>{\n`,
footer: '})();',
intro: getWorkerIntro(workerMsgId, config.devMode),
esModule: false,
externalLiveBindings: false,
});
const entryPoint = output.output[0];
if (entryPoint.imports.length > 0) {
ctx.error('Workers should not have any external imports: ' + JSON.stringify(entryPoint.imports));
}
// Optimize code
let code = entryPoint.code;
const results = await optimizeModule(config, compilerCtx, {
input: code,
sourceTarget: config.buildEs5 ? 'es5' : 'es2017',
isCore: false,
minify: config.minifyJs,
inlineHelpers: true,
});
buildCtx.diagnostics.push(...results.diagnostics);
if (!hasError(results.diagnostics)) {
code = results.output;
}
return {
code,
exports: entryPoint.exports,
workerMsgId,
dependencies: Object.keys(entryPoint.modules).filter((id) => !/\0/.test(id) && id !== workerEntryPath),
};
}
return null;
};
const WORKER_SUFFIX = ['.worker.ts', '.worker.tsx', '.worker/index.ts', '.worker/index.tsx'];
const WORKER_HELPER_ID = '@worker-helper';
const GET_TRANSFERABLES = `
const isInstanceOf = (value, className) => {
const C = globalThis[className];
return C != null && value instanceof C;
}
const getTransferables = (value) => {
if (value != null) {
if (
isInstanceOf(value, "ArrayBuffer") ||
isInstanceOf(value, "MessagePort") ||
isInstanceOf(value, "ImageBitmap") ||
isInstanceOf(value, "OffscreenCanvas")
) {
return [value];
}
if (typeof value === "object") {
if (value.constructor === Object) {
value = Object.values(value);
}
if (Array.isArray(value)) {
return value.flatMap(getTransferables);
}
return getTransferables(value.buffer);
}
}
return [];
};`;
const getWorkerIntro = (workerMsgId: string, isDev: boolean) => `
${GET_TRANSFERABLES}
const exports = {};
const workerMsgId = '${workerMsgId}';
const workerMsgCallbackId = workerMsgId + '.cb';
addEventListener('message', async ({data}) => {
if (data && data[0] === workerMsgId) {
let id = data[1];
let method = data[2];
let args = data[3];
let i = 0;
let argsLen = args.length;
let value;
let err;
try {
for (; i < argsLen; i++) {
if (Array.isArray(args[i]) && args[i][0] === workerMsgCallbackId) {
const callbackId = args[i][1];
args[i] = (...cbArgs) => {
postMessage(
[workerMsgCallbackId, callbackId, cbArgs]
);
};
}
}
${
isDev
? `
value = exports[method](...args);
if (!value || !value.then) {
throw new Error('The exported method "' + method + '" does not return a Promise, make sure it is an "async" function');
}
value = await value;
`
: `
value = await exports[method](...args);`
}
} catch (e) {
value = null;
if (e instanceof Error) {
err = {
isError: true,
value: {
message: e.message,
name: e.name,
stack: e.stack,
}
};
} else {
err = {
isError: false,
value: e
};
}
value = undefined;
}
const transferables = getTransferables(value);
${isDev ? `if (transferables.length > 0) console.debug('Transfering', transferables);` : ''}
postMessage(
[workerMsgId, id, value, err],
transferables
);
}
});
`;
export const WORKER_HELPERS = `
import { consoleError } from '${STENCIL_INTERNAL_ID}';
${GET_TRANSFERABLES}
let pendingIds = 0;
let callbackIds = 0;
const pending = new Map();
const callbacks = new Map();
export const createWorker = (workerPath, workerName, workerMsgId) => {
const worker = new Worker(workerPath, {name:workerName});
worker.addEventListener('message', ({data}) => {
if (data) {
const workerMsg = data[0];
const id = data[1];
const value = data[2];
if (workerMsg === workerMsgId) {
const err = data[3];
const [resolve, reject, callbackIds] = pending.get(id);
pending.delete(id);
if (err) {
const errObj = (err.isError)
? Object.assign(new Error(err.value.message), err.value)
: err.value;
consoleError(errObj);
reject(errObj);
} else {
if (callbackIds) {
callbackIds.forEach(id => callbacks.delete(id));
}
resolve(value);
}
} else if (workerMsg === workerMsgId + '.cb') {
try {
callbacks.get(id)(...value);
} catch (e) {
consoleError(e);
}
}
}
});
return worker;
};
export const createWorkerProxy = (worker, workerMsgId, exportedMethod) => (
(...args) => new Promise((resolve, reject) => {
let pendingId = pendingIds++;
let i = 0;
let argLen = args.length;
let mainData = [resolve, reject];
pending.set(pendingId, mainData);
for (; i < argLen; i++) {
if (typeof args[i] === 'function') {
const callbackId = callbackIds++;
callbacks.set(callbackId, args[i]);
args[i] = [workerMsgId + '.cb', callbackId];
(mainData[2] = mainData[2] || []).push(callbackId);
}
}
const postMessage = (w) => (
w.postMessage(
[workerMsgId, pendingId, exportedMethod, args],
getTransferables(args)
)
);
if (worker.then) {
worker.then(postMessage);
} else {
postMessage(worker);
}
})
);
`;
const getWorkerMain = (referenceId: string, workerName: string, workerMsgId: string) => {
return `
import { createWorker } from '${WORKER_HELPER_ID}';
export const workerName = '${workerName}';
export const workerMsgId = '${workerMsgId}';
export const workerPath = /*@__PURE__*/import.meta.ROLLUP_FILE_URL_${referenceId};
export const worker = /*@__PURE__*/createWorker(workerPath, workerName, workerMsgId);
`;
};
const getInlineWorker = (referenceId: string, workerName: string, workerMsgId: string) => {
return `
import { createWorker } from '${WORKER_HELPER_ID}';
export const workerName = '${workerName}';
export const workerMsgId = '${workerMsgId}';
export const workerPath = /*@__PURE__*/import.meta.ROLLUP_FILE_URL_${referenceId};
export let worker;
try {
// first try directly starting the worker with the URL
worker = /*@__PURE__*/createWorker(workerPath, workerName, workerMsgId);
} catch(e) {
// probably a cross-origin issue, try using a Blob instead
const blob = new Blob(['importScripts("' + workerPath + '")'], { type: 'text/javascript' });
const url = URL.createObjectURL(blob);
worker = /*@__PURE__*/createWorker(url, workerName, workerMsgId);
URL.revokeObjectURL(url);
}
`;
};
const getMockedWorkerMain = () => {
// for the hydrate build the workers won't actually work
// however, we still need to make the {worker} export
// kick-in otherwise bundling chokes
return `
export const workerName = 'mocked-worker';
export const workerMsgId = workerName;
export const workerPath = workerName;
export const worker = { name: workerName };
`;
};
const getWorkerProxy = (workerEntryPath: string, exportedMethods: string[]) => {
return `
import { createWorkerProxy } from '${WORKER_HELPER_ID}';
import { worker, workerName, workerMsgId } from '${workerEntryPath}?worker';
${exportedMethods
.map((exportedMethod) => {
return `export const ${exportedMethod} = /*@__PURE__*/createWorkerProxy(worker, workerMsgId, '${exportedMethod}');`;
})
.join('\n')}
`;
};
const getInlineWorkerProxy = (workerEntryPath: string, workerMsgId: string, exportedMethods: string[]) => {
return `
import { createWorkerProxy } from '${WORKER_HELPER_ID}';
const workerPromise = import('${workerEntryPath}?worker-inline').then(m => m.worker);
${exportedMethods
.map((exportedMethod) => {
return `export const ${exportedMethod} = /*@__PURE__*/createWorkerProxy(workerPromise, '${workerMsgId}', '${exportedMethod}');`;
})
.join('\n')}
`;
};
================================================
FILE: src/compiler/cache.ts
================================================
import { join } from '@utils';
import type * as d from '../declarations';
import { InMemoryFileSystem } from './sys/in-memory-fs';
export class Cache implements d.Cache {
private failed = 0;
private skip = false;
private sys: d.CompilerSystem;
private logger: d.Logger;
private buildCacheDir: string;
constructor(
private config: d.ValidatedConfig,
private cacheFs: InMemoryFileSystem,
) {
this.sys = config.sys;
this.logger = config.logger;
}
async initCacheDir() {
if (this.config._isTesting || !this.config.cacheDir) {
return;
}
this.buildCacheDir = join(this.config.cacheDir, '.build');
if (!this.config.enableCache || !this.cacheFs) {
this.config.logger.info(`cache optimizations disabled`);
this.clearDiskCache();
return;
}
this.config.logger.debug(`cache enabled, cacheDir: ${this.buildCacheDir}`);
try {
const readmeFilePath = join(this.buildCacheDir, '_README.log');
await this.cacheFs.writeFile(readmeFilePath, CACHE_DIR_README);
} catch (e) {
this.logger.error(`Cache, initCacheDir: ${e}`);
this.config.enableCache = false;
}
}
async get(key: string) {
if (!this.config.enableCache || this.skip) {
return null;
}
if (this.failed >= MAX_FAILED) {
if (!this.skip) {
this.skip = true;
this.logger.debug(`cache had ${this.failed} failed ops, skip disk ops for remainder of build`);
}
return null;
}
let result: string | null;
try {
result = await this.cacheFs.readFile(this.getCacheFilePath(key));
this.failed = 0;
this.skip = false;
} catch (e: unknown) {
this.failed++;
result = null;
}
return result;
}
async put(key: string, value: string) {
if (!this.config.enableCache) {
return false;
}
try {
await this.cacheFs.writeFile(this.getCacheFilePath(key), value);
return true;
} catch (e: unknown) {
this.failed++;
return false;
}
}
async has(key: string) {
const val = await this.get(key);
return typeof val === 'string';
}
async createKey(domain: string, ...args: any[]) {
if (!this.config.enableCache || !this.sys.generateContentHash) {
return domain + Math.random() * 9999999;
}
const hash = await this.sys.generateContentHash(JSON.stringify(args), 32);
return domain + '_' + hash;
}
async commit() {
if (this.config.enableCache) {
this.skip = false;
this.failed = 0;
await this.cacheFs.commit();
await this.clearExpiredCache();
}
}
clear() {
if (this.cacheFs != null) {
this.cacheFs.clearCache();
}
}
async clearExpiredCache() {
if (this.cacheFs == null || this.sys.cacheStorage == null) {
return;
}
const now = Date.now();
const lastClear = (await this.sys.cacheStorage.get(EXP_STORAGE_KEY)) as number;
if (lastClear != null) {
const diff = now - lastClear;
if (diff < ONE_DAY) {
return;
}
const fs = this.cacheFs.sys;
const cachedFileNames = await fs.readDir(this.buildCacheDir);
const cachedFilePaths = cachedFileNames.map((f) => join(this.buildCacheDir, f));
let totalCleared = 0;
const promises = cachedFilePaths.map(async (filePath) => {
const stat = await fs.stat(filePath);
const lastModified = stat.mtimeMs;
if (lastModified && now - lastModified > ONE_WEEK) {
await fs.removeFile(filePath);
totalCleared++;
}
});
await Promise.all(promises);
this.logger.debug(`clearExpiredCache, cachedFileNames: ${cachedFileNames.length}, totalCleared: ${totalCleared}`);
}
this.logger.debug(`clearExpiredCache, set last clear`);
await this.sys.cacheStorage.set(EXP_STORAGE_KEY, now);
}
async clearDiskCache() {
if (this.cacheFs != null) {
const hasAccess = await this.cacheFs.access(this.buildCacheDir);
if (hasAccess) {
await this.cacheFs.remove(this.buildCacheDir);
await this.cacheFs.commit();
}
}
}
private getCacheFilePath(key: string): string {
return join(this.buildCacheDir, key) + '.log';
}
getMemoryStats(): string | null {
if (this.cacheFs != null) {
return this.cacheFs.getMemoryStats();
}
return null;
}
}
const MAX_FAILED = 100;
const ONE_DAY = 1000 * 60 * 60 * 24;
const ONE_WEEK = ONE_DAY * 7;
const EXP_STORAGE_KEY = `last_clear_expired_cache`;
const CACHE_DIR_README = `# Stencil Cache Directory
This directory contains files which the compiler has
cached for faster builds. To disable caching, please set
"enableCache: false" within the stencil config.
To change the cache directory, please update the
"cacheDir" property within the stencil config.
`;
================================================
FILE: src/compiler/compiler.ts
================================================
import { isFunction } from '@utils';
import ts from 'typescript';
import type { Compiler, Config, Diagnostic, ValidatedConfig } from '../declarations';
import { CompilerContext } from './build/compiler-ctx';
import { createFullBuild } from './build/full-build';
import { createWatchBuild } from './build/watch-build';
import { Cache } from './cache';
import { getConfig } from './sys/config';
import { createInMemoryFs } from './sys/in-memory-fs';
import { resolveModuleIdAsync } from './sys/resolve/resolve-module-async';
import { patchTypescript } from './sys/typescript/typescript-sys';
import { createSysWorker } from './sys/worker/sys-worker';
/**
* Generate a Stencil compiler instance
* @param userConfig a user-provided Stencil configuration to apply to the compiler instance
* @returns a new instance of a Stencil compiler
* @public
*/
export const createCompiler = async (userConfig: Config): Promise => {
// actual compiler code
const config: ValidatedConfig = getConfig(userConfig);
const diagnostics: Diagnostic[] = [];
const sys = config.sys;
const compilerCtx = new CompilerContext();
if (isFunction(config.sys.setupCompiler)) {
config.sys.setupCompiler({ ts });
}
compilerCtx.fs = createInMemoryFs(sys);
compilerCtx.cache = new Cache(config, createInMemoryFs(sys));
await compilerCtx.cache.initCacheDir();
sys.resolveModuleId = (opts) => resolveModuleIdAsync(sys, compilerCtx.fs, opts);
compilerCtx.worker = createSysWorker(config);
if (sys.events) {
// Pipe events from sys.events to compilerCtx
sys.events.on(compilerCtx.events.emit);
}
patchTypescript(config, compilerCtx.fs);
const build = () => createFullBuild(config, compilerCtx);
const createWatcher = () => createWatchBuild(config, compilerCtx);
const destroy = async () => {
compilerCtx.reset();
compilerCtx.events.unsubscribeAll();
await sys.destroy();
};
const compiler: Compiler = {
build,
createWatcher,
destroy,
sys,
};
config.logger.printDiagnostics(diagnostics);
return compiler;
};
================================================
FILE: src/compiler/config/config-utils.ts
================================================
import { isBoolean, join } from '@utils';
import { isAbsolute } from 'path';
import type { ConfigFlags } from '../../cli/config-flags';
import type * as d from '../../declarations';
export const getAbsolutePath = (config: d.ValidatedConfig, dir: string) => {
if (!isAbsolute(dir)) {
dir = join(config.rootDir, dir);
}
return dir;
};
/**
* This function does two things:
*
* 1. If you pass a `flagName`, it will hoist that `flagName` out of the
* `ConfigFlags` object and onto the 'root' level (if you will) of the
* `config` under the `configName` (`keyof d.Config`) that you pass.
* 2. If you _don't_ pass a `flagName` it will just set the value you supply
* on the config.
*
* @param config the config that we want to update
* @param configName the key we're setting on the config
* @param flagName either the name of a ConfigFlag prop we want to hoist up or null
* @param defaultValue the default value we should set!
*/
export const setBooleanConfig = (
config: d.UnvalidatedConfig,
configName: (K & keyof ConfigFlags) | K,
flagName: keyof ConfigFlags | null,
defaultValue: d.Config[K],
) => {
if (flagName) {
const flagValue = config.flags?.[flagName];
if (isBoolean(flagValue)) {
config[configName] = flagValue;
}
}
const userConfigName = getUserConfigName(config, configName);
if (typeof config[userConfigName] === 'function') {
config[userConfigName] = !!config[userConfigName]();
}
if (isBoolean(config[userConfigName])) {
config[configName] = config[userConfigName];
} else {
config[configName] = defaultValue;
}
};
/**
* Find any possibly mis-capitalized configuration names on the config, logging
* and warning if one is found.
*
* @param config the user-supplied config that we're dealing with
* @param correctConfigName the configuration name that we're checking for right now
* @returns a string container a mis-capitalized config name found on the
* config object, if any.
*/
const getUserConfigName = (config: d.UnvalidatedConfig, correctConfigName: keyof d.Config): string => {
const userConfigNames = Object.keys(config);
for (const userConfigName of userConfigNames) {
if (userConfigName.toLowerCase() === correctConfigName.toLowerCase()) {
if (userConfigName !== correctConfigName) {
config.logger?.warn(`config "${userConfigName}" should be "${correctConfigName}"`);
return userConfigName;
}
break;
}
}
return correctConfigName;
};
================================================
FILE: src/compiler/config/constants.ts
================================================
import type * as d from '../../declarations';
type DefaultTargetComponentConfig = d.Config['docs']['markdown']['targetComponent'];
export const DEFAULT_DEV_MODE = false;
export const DEFAULT_HASHED_FILENAME_LENGTH = 8;
export const MIN_HASHED_FILENAME_LENGTH = 4;
export const MAX_HASHED_FILENAME_LENGTH = 32;
export const DEFAULT_NAMESPACE = 'App';
export const DEFAULT_TARGET_COMPONENT_STYLES: DefaultTargetComponentConfig = {
background: '#f9f',
textColor: '#333',
};
================================================
FILE: src/compiler/config/load-config.ts
================================================
import { createNodeSys } from '@sys-api-node';
import { buildError, catchError, hasError, isString, normalizePath } from '@utils';
import { dirname } from 'path';
import type { Diagnostic, LoadConfigInit, LoadConfigResults, UnvalidatedConfig } from '../../declarations';
import { nodeRequire } from '../sys/node-require';
import { validateTsConfig } from '../sys/typescript/typescript-config';
import { validateConfig } from './validate-config';
/**
* Load and validate a configuration to use throughout the lifetime of any Stencil task (build, test, etc.).
*
* Users can provide configurations multiple ways simultaneously:
* - as an object of the `init` argument to this function
* - through a path to a configuration file that exists on disk
*
* In the case of both being present, the two configurations will be merged. The fields of the former will take precedence
* over the fields of the latter.
*
* @param init the initial configuration provided by the user (or generated by Stencil) used to bootstrap configuration
* loading and validation
* @returns the results of loading a configuration
* @public
*/
export const loadConfig = async (init: LoadConfigInit = {}): Promise => {
const results: LoadConfigResults = {
config: null,
diagnostics: [],
tsconfig: {
path: null,
compilerOptions: null,
files: null,
include: null,
exclude: null,
extends: null,
},
};
const unknownConfig: UnvalidatedConfig = {};
try {
const config = init.config || {};
let configPath = init.configPath || config.configPath;
// Pull the {@link CompilerSystem} out of the initialization object, or create one if it does not exist.
// This entity is needed to load the project's configuration (and therefore needs to be created before it can be
// attached to a configuration entity, validated or otherwise)
const sys = init.sys ?? createNodeSys();
const loadedConfigFile = await loadConfigFile(results.diagnostics, configPath);
if (hasError(results.diagnostics)) {
return results;
}
if (loadedConfigFile !== null) {
// merge the user's config object into their loaded config file
configPath = loadedConfigFile.configPath;
unknownConfig.config = { ...loadedConfigFile, ...config };
unknownConfig.config.configPath = configPath;
unknownConfig.config.rootDir =
typeof config.rootDir === 'string' ? config.rootDir : normalizePath(dirname(configPath));
} else {
// no stencil.config.ts or .js file, which is fine
unknownConfig.config = { ...config };
unknownConfig.config.configPath = null;
unknownConfig.config.rootDir = normalizePath(sys.getCurrentDirectory());
}
unknownConfig.config.sys = sys;
const validated = validateConfig(unknownConfig.config, init);
results.diagnostics.push(...validated.diagnostics);
if (hasError(results.diagnostics)) {
return results;
}
results.config = validated.config;
if (!hasError(results.diagnostics)) {
const tsConfigResults = await validateTsConfig(results.config, sys, init);
results.diagnostics.push(...tsConfigResults.diagnostics);
results.config.tsconfig = tsConfigResults.path;
results.config.tsCompilerOptions = tsConfigResults.compilerOptions;
results.config.tsWatchOptions = tsConfigResults.watchOptions;
results.tsconfig.path = tsConfigResults.path;
results.tsconfig.compilerOptions = JSON.parse(JSON.stringify(tsConfigResults.compilerOptions));
results.tsconfig.files = tsConfigResults.files;
results.tsconfig.include = tsConfigResults.include;
results.tsconfig.exclude = tsConfigResults.exclude;
results.tsconfig.extends = tsConfigResults.extends;
}
} catch (e: any) {
catchError(results.diagnostics, e);
}
return results;
};
/**
* Load a Stencil configuration file from disk
*
* @param diagnostics a series of diagnostics used to track errors & warnings
* throughout the loading process. Entries may be added to this list in the
* event of an error.
* @param configPath the path to the configuration file to load
* @returns an unvalidated configuration. In the event of an error, additional
* diagnostics may be pushed to the provided `diagnostics` argument and `null`
* will be returned.
*/
const loadConfigFile = async (diagnostics: Diagnostic[], configPath: string): Promise => {
let config: UnvalidatedConfig | null = null;
if (isString(configPath)) {
// the passed in config was a string, so it's probably a path to the config we need to load
const configFileData = await evaluateConfigFile(diagnostics, configPath);
if (hasError(diagnostics)) {
return config;
}
if (!configFileData.config) {
const err = buildError(diagnostics);
err.messageText = `Invalid Stencil configuration file "${configPath}". Missing "config" property.`;
err.absFilePath = configPath;
return config;
}
config = configFileData.config;
config.configPath = normalizePath(configPath);
}
return config;
};
/**
* Load the configuration file, based on the environment that Stencil is being run in
*
* @param diagnostics a series of diagnostics used to track errors & warnings
* throughout the loading process. Entries may be added to this list in the
* event of an error.
* @param configFilePath the path to the configuration file to load
* @returns an unvalidated configuration. In the event of an error, additional
* diagnostics may be pushed to the provided `diagnostics` argument and `null`
* will be returned.
*/
const evaluateConfigFile = async (
diagnostics: Diagnostic[],
configFilePath: string,
): Promise<{ config?: UnvalidatedConfig } | null> => {
let configFileData: { config?: UnvalidatedConfig } | null = null;
try {
const results = nodeRequire(configFilePath);
diagnostics.push(...results.diagnostics);
configFileData = results.module;
} catch (e: any) {
catchError(diagnostics, e);
}
return configFileData;
};
================================================
FILE: src/compiler/config/outputs/index.ts
================================================
import { buildError, isValidConfigOutputTarget, VALID_CONFIG_OUTPUT_TARGETS } from '@utils';
import type * as d from '../../../declarations';
import { validateCollection } from './validate-collection';
import { validateCustomElement } from './validate-custom-element';
import { validateCustomOutput } from './validate-custom-output';
import { validateDist } from './validate-dist';
import { validateDocs } from './validate-docs';
import { validateHydrateScript } from './validate-hydrate-script';
import { validateLazy } from './validate-lazy';
import { validateStats } from './validate-stats';
import { validateWww } from './validate-www';
export const validateOutputTargets = (config: d.ValidatedConfig, diagnostics: d.Diagnostic[]) => {
const userOutputs = (config.outputTargets || []).slice();
userOutputs.forEach((outputTarget) => {
if (!isValidConfigOutputTarget(outputTarget.type)) {
const err = buildError(diagnostics);
err.messageText = `Invalid outputTarget type "${
outputTarget.type
}". Valid outputTarget types include: ${VALID_CONFIG_OUTPUT_TARGETS.map((t) => `"${t}"`).join(', ')}`;
}
});
config.outputTargets = [
...validateCollection(config, userOutputs),
...validateCustomElement(config, userOutputs),
...validateCustomOutput(config, diagnostics, userOutputs),
...validateLazy(config, userOutputs),
...validateWww(config, diagnostics, userOutputs),
...validateDist(config, userOutputs),
...validateDocs(config, diagnostics, userOutputs),
...validateStats(config, userOutputs),
];
// hydrate also gets info from the www output
config.outputTargets = [
...config.outputTargets,
...validateHydrateScript(config, [...userOutputs, ...config.outputTargets]),
];
};
================================================
FILE: src/compiler/config/outputs/validate-collection.ts
================================================
import { isBoolean, isOutputTargetDistCollection } from '@utils';
import type * as d from '../../../declarations';
import { getAbsolutePath } from '../config-utils';
/**
* Validate and return DIST_COLLECTION output targets, ensuring that the `dir`
* property is set on them.
*
* @param config a validated configuration object
* @param userOutputs an array of output targets
* @returns an array of validated DIST_COLLECTION output targets
*/
export const validateCollection = (
config: d.ValidatedConfig,
userOutputs: d.OutputTarget[],
): d.OutputTargetDistCollection[] => {
return userOutputs.filter(isOutputTargetDistCollection).map((outputTarget) => {
return {
...outputTarget,
transformAliasedImportPaths: isBoolean(outputTarget.transformAliasedImportPaths)
? outputTarget.transformAliasedImportPaths
: true,
dir: getAbsolutePath(config, outputTarget.dir ?? 'dist/collection'),
};
});
};
================================================
FILE: src/compiler/config/outputs/validate-custom-element.ts
================================================
import { COPY, DIST_TYPES, isBoolean, isOutputTargetDistCustomElements, join } from '@utils';
import type {
OutputTarget,
OutputTargetCopy,
OutputTargetDistCustomElements,
OutputTargetDistTypes,
ValidatedConfig,
} from '../../../declarations';
import { CustomElementsExportBehaviorOptions } from '../../../declarations';
import { getAbsolutePath } from '../config-utils';
import { validateCopy } from '../validate-copy';
/**
* Validate one or more `dist-custom-elements` output targets. Validation of an output target may involve back-filling
* fields that are omitted with sensible defaults and/or creating additional supporting output targets that were not
* explicitly defined by the user
* @param config the Stencil configuration associated with the project being compiled
* @param userOutputs the output target(s) specified by the user
* @returns the validated output target(s)
*/
export const validateCustomElement = (
config: ValidatedConfig,
userOutputs: ReadonlyArray,
): ReadonlyArray => {
const defaultDir = 'dist';
return userOutputs.filter(isOutputTargetDistCustomElements).reduce(
(outputs, o) => {
const outputTarget = {
...o,
dir: getAbsolutePath(config, o.dir || join(defaultDir, 'components')),
};
if (!isBoolean(outputTarget.empty)) {
outputTarget.empty = true;
}
if (!isBoolean(outputTarget.externalRuntime)) {
outputTarget.externalRuntime = true;
}
if (!isBoolean(outputTarget.generateTypeDeclarations)) {
outputTarget.generateTypeDeclarations = true;
}
// Export behavior must be defined on the validated target config and must
// be one of the export behavior valid values
if (
outputTarget.customElementsExportBehavior == null ||
!CustomElementsExportBehaviorOptions.includes(outputTarget.customElementsExportBehavior)
) {
outputTarget.customElementsExportBehavior = 'default';
}
// Normalize autoLoader option
if (outputTarget.autoLoader === true) {
outputTarget.autoLoader = {
fileName: 'loader',
autoStart: true,
};
} else if (outputTarget.autoLoader && typeof outputTarget.autoLoader === 'object') {
outputTarget.autoLoader = {
fileName: outputTarget.autoLoader.fileName || 'loader',
autoStart: outputTarget.autoLoader.autoStart !== false,
};
}
// unlike other output targets, Stencil does not allow users to define the output location of types at this time
if (outputTarget.generateTypeDeclarations) {
const typesDirectory = getAbsolutePath(config, join(defaultDir, 'types'));
outputs.push({
type: DIST_TYPES,
dir: outputTarget.dir,
typesDir: typesDirectory,
});
}
outputTarget.copy = validateCopy(outputTarget.copy, []);
if (outputTarget.copy.length > 0) {
outputs.push({
type: COPY,
dir: config.rootDir,
copy: [...outputTarget.copy],
});
}
outputs.push(outputTarget);
return outputs;
},
[] as (OutputTargetDistCustomElements | OutputTargetCopy | OutputTargetDistTypes)[],
);
};
================================================
FILE: src/compiler/config/outputs/validate-custom-output.ts
================================================
import { catchError, COPY, isOutputTargetCustom } from '@utils';
import type * as d from '../../../declarations';
export const validateCustomOutput = (
config: d.ValidatedConfig,
diagnostics: d.Diagnostic[],
userOutputs: d.OutputTarget[],
) => {
return userOutputs.filter(isOutputTargetCustom).map((o) => {
if (o.validate) {
const localDiagnostics: d.Diagnostic[] = [];
try {
o.validate(config, diagnostics);
} catch (e: any) {
catchError(localDiagnostics, e);
}
if (o.copy && o.copy.length > 0) {
config.outputTargets.push({
type: COPY,
dir: config.rootDir,
copy: [...o.copy],
});
}
diagnostics.push(...localDiagnostics);
}
return o;
});
};
================================================
FILE: src/compiler/config/outputs/validate-dist.ts
================================================
import {
COPY,
DIST_COLLECTION,
DIST_GLOBAL_STYLES,
DIST_LAZY,
DIST_LAZY_LOADER,
DIST_TYPES,
getComponentsDtsTypesFilePath,
isBoolean,
isOutputTargetDist,
isString,
join,
resolve,
} from '@utils';
import { isAbsolute } from 'path';
import type * as d from '../../../declarations';
import { getAbsolutePath } from '../config-utils';
import { validateCopy } from '../validate-copy';
/**
* Validate that the "dist" output targets are valid and ready to go.
*
* This function will also add in additional output targets to its output, based on the input supplied.
*
* @param config the compiler config, what else?
* @param userOutputs a user-supplied list of output targets.
* @returns a list of OutputTargets which have been validated for us.
*/
export const validateDist = (config: d.ValidatedConfig, userOutputs: d.OutputTarget[]): d.OutputTarget[] => {
const distOutputTargets = userOutputs.filter(isOutputTargetDist);
const outputs: d.OutputTarget[] = [];
for (const outputTarget of distOutputTargets) {
const distOutputTarget = validateOutputTargetDist(config, outputTarget);
outputs.push(distOutputTarget);
const namespace = config.fsNamespace || 'app';
const lazyDir = join(distOutputTarget.buildDir, namespace);
// Lazy build for CDN in dist
outputs.push({
type: DIST_LAZY,
esmDir: lazyDir,
systemDir: config.buildEs5 ? lazyDir : undefined,
systemLoaderFile: config.buildEs5 ? join(lazyDir, namespace + '.js') : undefined,
legacyLoaderFile: join(distOutputTarget.buildDir, namespace + '.js'),
polyfills: outputTarget.polyfills !== undefined ? !!distOutputTarget.polyfills : true,
isBrowserBuild: true,
empty: distOutputTarget.empty,
});
outputs.push({
type: COPY,
dir: lazyDir,
copyAssets: 'dist',
copy: (distOutputTarget.copy ?? []).concat(),
});
outputs.push({
type: DIST_GLOBAL_STYLES,
file: join(lazyDir, `${config.fsNamespace}.css`),
});
outputs.push({
type: DIST_TYPES,
dir: distOutputTarget.dir,
typesDir: distOutputTarget.typesDir,
});
if (config.buildDist) {
if (distOutputTarget.collectionDir) {
outputs.push({
type: DIST_COLLECTION,
dir: distOutputTarget.dir,
collectionDir: distOutputTarget.collectionDir,
empty: distOutputTarget.empty,
transformAliasedImportPaths: distOutputTarget.transformAliasedImportPathsInCollection,
});
outputs.push({
type: COPY,
dir: distOutputTarget.collectionDir,
copyAssets: 'collection',
copy: [...distOutputTarget.copy, { src: '**/*.svg' }, { src: '**/*.js' }],
});
}
const esmDir = join(distOutputTarget.dir, 'esm');
const esmEs5Dir = config.buildEs5 ? join(distOutputTarget.dir, 'esm-es5') : undefined;
const cjsDir = join(distOutputTarget.dir, 'cjs');
// Create lazy output-target
outputs.push({
type: DIST_LAZY,
esmDir,
esmEs5Dir,
cjsDir,
cjsIndexFile: join(distOutputTarget.dir, 'index.cjs.js'),
esmIndexFile: join(distOutputTarget.dir, 'index.js'),
polyfills: true,
empty: distOutputTarget.empty,
});
// Create output target that will generate the /loader entry-point
outputs.push({
type: DIST_LAZY_LOADER,
dir: distOutputTarget.esmLoaderPath,
esmDir,
esmEs5Dir,
cjsDir,
componentDts: getComponentsDtsTypesFilePath(distOutputTarget),
empty: distOutputTarget.empty,
});
}
}
return outputs;
};
/**
* Validate that an OutputTargetDist object has what it needs to do it's job.
* To enforce this, we have this function return
* `Required`, giving us a compile-time check that all
* properties are defined (with either user-supplied or default values).
*
* @param config the current config
* @param o the OutputTargetDist object we want to validate
* @returns `Required`, i.e. `d.OutputTargetDist` with all
* optional properties rendered un-optional.
*/
const validateOutputTargetDist = (config: d.ValidatedConfig, o: d.OutputTargetDist): Required => {
// we need to create an object with a bunch of default values here so that
// the typescript compiler can infer their types correctly
const outputTarget = {
...o,
dir: getAbsolutePath(config, o.dir || DEFAULT_DIR),
buildDir: isString(o.buildDir) ? o.buildDir : DEFAULT_BUILD_DIR,
collectionDir: o.collectionDir !== undefined ? o.collectionDir : DEFAULT_COLLECTION_DIR,
typesDir: o.typesDir || DEFAULT_TYPES_DIR,
esmLoaderPath: o.esmLoaderPath || DEFAULT_ESM_LOADER_DIR,
copy: validateCopy(o.copy ?? [], []),
polyfills: isBoolean(o.polyfills) ? o.polyfills : false,
empty: isBoolean(o.empty) ? o.empty : true,
transformAliasedImportPathsInCollection: isBoolean(o.transformAliasedImportPathsInCollection)
? o.transformAliasedImportPathsInCollection
: true,
isPrimaryPackageOutputTarget: o.isPrimaryPackageOutputTarget ?? false,
} satisfies Required;
if (!isAbsolute(outputTarget.buildDir)) {
outputTarget.buildDir = join(outputTarget.dir, outputTarget.buildDir);
}
if (outputTarget.collectionDir && !isAbsolute(outputTarget.collectionDir)) {
outputTarget.collectionDir = join(outputTarget.dir, outputTarget.collectionDir);
}
if (!isAbsolute(outputTarget.esmLoaderPath)) {
outputTarget.esmLoaderPath = resolve(outputTarget.dir, outputTarget.esmLoaderPath);
}
if (!isAbsolute(outputTarget.typesDir)) {
outputTarget.typesDir = join(outputTarget.dir, outputTarget.typesDir);
}
return outputTarget;
};
const DEFAULT_DIR = 'dist';
const DEFAULT_BUILD_DIR = '';
const DEFAULT_COLLECTION_DIR = 'collection';
const DEFAULT_TYPES_DIR = 'types';
const DEFAULT_ESM_LOADER_DIR = 'loader';
================================================
FILE: src/compiler/config/outputs/validate-docs.ts
================================================
import {
buildError,
DOCS_JSON,
DOCS_README,
isFunction,
isOutputTargetDocsCustom,
isOutputTargetDocsCustomElementsManifest,
isOutputTargetDocsJson,
isOutputTargetDocsReadme,
isOutputTargetDocsVscode,
isString,
join,
} from '@utils';
import { isAbsolute } from 'path';
import type * as d from '../../../declarations';
import { NOTE } from '../../docs/constants';
export const validateDocs = (config: d.ValidatedConfig, diagnostics: d.Diagnostic[], userOutputs: d.OutputTarget[]) => {
const docsOutputs: d.OutputTarget[] = [];
// json docs flag
if (isString(config.flags.docsJson)) {
docsOutputs.push(
validateJsonDocsOutputTarget(config, diagnostics, {
type: DOCS_JSON,
file: config.flags.docsJson,
}),
);
}
// json docs
const jsonDocsOutputs = userOutputs.filter(isOutputTargetDocsJson);
jsonDocsOutputs.forEach((jsonDocsOutput) => {
docsOutputs.push(validateJsonDocsOutputTarget(config, diagnostics, jsonDocsOutput));
});
// readme docs flag
if (config.flags.docs || config.flags.task === 'docs') {
if (!userOutputs.some(isOutputTargetDocsReadme)) {
// didn't provide a docs config, so let's add one
docsOutputs.push(validateReadmeOutputTarget(config, { type: DOCS_README }));
}
}
// readme docs
const readmeDocsOutputs = userOutputs.filter(isOutputTargetDocsReadme);
readmeDocsOutputs.forEach((readmeDocsOutput) => {
docsOutputs.push(validateReadmeOutputTarget(config, readmeDocsOutput));
});
// custom docs
const customDocsOutputs = userOutputs.filter(isOutputTargetDocsCustom);
customDocsOutputs.forEach((jsonDocsOutput) => {
docsOutputs.push(validateCustomDocsOutputTarget(diagnostics, jsonDocsOutput));
});
// vscode docs
const vscodeDocsOutputs = userOutputs.filter(isOutputTargetDocsVscode);
vscodeDocsOutputs.forEach((vscodeDocsOutput) => {
docsOutputs.push(validateVScodeDocsOutputTarget(diagnostics, vscodeDocsOutput));
});
// custom elements manifest docs
const customElementsManifestOutputs = userOutputs.filter(isOutputTargetDocsCustomElementsManifest);
customElementsManifestOutputs.forEach((cemOutput) => {
docsOutputs.push(validateCustomElementsManifestOutputTarget(config, cemOutput));
});
return docsOutputs;
};
const validateReadmeOutputTarget = (config: d.ValidatedConfig, outputTarget: d.OutputTargetDocsReadme) => {
if (!isString(outputTarget.dir)) {
outputTarget.dir = config.srcDir;
}
if (!isAbsolute(outputTarget.dir)) {
outputTarget.dir = join(config.rootDir, outputTarget.dir);
}
if (outputTarget.footer == null) {
outputTarget.footer = NOTE;
}
outputTarget.strict = !!outputTarget.strict;
return outputTarget;
};
const validateJsonDocsOutputTarget = (
config: d.ValidatedConfig,
diagnostics: d.Diagnostic[],
outputTarget: d.OutputTargetDocsJson,
) => {
if (!isString(outputTarget.file)) {
const err = buildError(diagnostics);
err.messageText = `docs-json outputTarget missing the "file" option`;
}
outputTarget.file = join(config.rootDir, outputTarget.file);
if (isString(outputTarget.typesFile)) {
outputTarget.typesFile = join(config.rootDir, outputTarget.typesFile);
} else if (outputTarget.typesFile !== null && outputTarget.file.endsWith('.json')) {
outputTarget.typesFile = outputTarget.file.replace(/\.json$/, '.d.ts');
}
outputTarget.strict = !!outputTarget.strict;
return outputTarget;
};
const validateCustomDocsOutputTarget = (diagnostics: d.Diagnostic[], outputTarget: d.OutputTargetDocsCustom) => {
if (!isFunction(outputTarget.generator)) {
const err = buildError(diagnostics);
err.messageText = `docs-custom outputTarget missing the "generator" function`;
}
outputTarget.strict = !!outputTarget.strict;
return outputTarget;
};
const validateVScodeDocsOutputTarget = (diagnostics: d.Diagnostic[], outputTarget: d.OutputTargetDocsVscode) => {
if (!isString(outputTarget.file)) {
const err = buildError(diagnostics);
err.messageText = `docs-vscode outputTarget missing the "file" path`;
}
return outputTarget;
};
const validateCustomElementsManifestOutputTarget = (
config: d.ValidatedConfig,
outputTarget: d.OutputTargetDocsCustomElementsManifest,
) => {
if (!isString(outputTarget.file)) {
outputTarget.file = 'custom-elements.json';
}
outputTarget.file = join(config.rootDir, outputTarget.file);
outputTarget.strict = !!outputTarget.strict;
return outputTarget;
};
================================================
FILE: src/compiler/config/outputs/validate-hydrate-script.ts
================================================
import {
DIST_HYDRATE_SCRIPT,
isBoolean,
isOutputTargetDist,
isOutputTargetHydrate,
isOutputTargetWww,
isString,
join,
} from '@utils';
import { isAbsolute } from 'path';
import type * as d from '../../../declarations';
export const validateHydrateScript = (config: d.ValidatedConfig, userOutputs: d.OutputTarget[]) => {
const output: d.OutputTargetHydrate[] = [];
const hasHydrateOutputTarget = userOutputs.some(isOutputTargetHydrate);
if (!hasHydrateOutputTarget) {
// we don't already have a hydrate output target
// let's still see if we require one because of other output targets
const hasWwwOutput = userOutputs.filter(isOutputTargetWww).some((o) => isString(o.indexHtml));
const shouldBuildHydrate = config.flags.prerender || config.flags.ssr;
if (hasWwwOutput && shouldBuildHydrate) {
// we're prerendering a www output target, so we'll need a hydrate app
let hydrateDir: string;
const distOutput = userOutputs.find(isOutputTargetDist);
if (distOutput != null && isString(distOutput.dir)) {
hydrateDir = join(distOutput.dir, 'hydrate');
} else {
hydrateDir = 'dist/hydrate';
}
const hydrateForWwwOutputTarget: d.OutputTargetHydrate = {
type: DIST_HYDRATE_SCRIPT,
dir: hydrateDir,
};
userOutputs.push(hydrateForWwwOutputTarget);
}
}
const hydrateOutputTargets = userOutputs.filter(isOutputTargetHydrate);
hydrateOutputTargets.forEach((outputTarget) => {
if (!isString(outputTarget.dir)) {
// no directory given, see if we've got a dist to go off of
outputTarget.dir = 'hydrate';
}
if (!isAbsolute(outputTarget.dir)) {
outputTarget.dir = join(config.rootDir, outputTarget.dir);
}
if (!isBoolean(outputTarget.empty)) {
outputTarget.empty = true;
}
if (!isBoolean(outputTarget.minify)) {
outputTarget.minify = false;
}
if (!isBoolean(outputTarget.generatePackageJson)) {
outputTarget.generatePackageJson = true;
}
outputTarget.external = outputTarget.external || [];
outputTarget.external.push('fs');
outputTarget.external.push('path');
outputTarget.external.push('crypto');
output.push(outputTarget);
});
return output;
};
================================================
FILE: src/compiler/config/outputs/validate-lazy.ts
================================================
import { DIST_LAZY, isBoolean, isOutputTargetDistLazy, join } from '@utils';
import type * as d from '../../../declarations';
import { getAbsolutePath } from '../config-utils';
export const validateLazy = (config: d.ValidatedConfig, userOutputs: d.OutputTarget[]) => {
return userOutputs.filter(isOutputTargetDistLazy).map((o) => {
const dir = getAbsolutePath(config, o.dir || join('dist', config.fsNamespace));
const lazyOutput: d.OutputTargetDistLazy = {
type: DIST_LAZY,
esmDir: dir,
systemDir: config.buildEs5 ? dir : undefined,
systemLoaderFile: config.buildEs5 ? join(dir, `${config.fsNamespace}.js`) : undefined,
polyfills: !!o.polyfills,
isBrowserBuild: true,
empty: isBoolean(o.empty) ? o.empty : true,
};
return lazyOutput;
});
};
================================================
FILE: src/compiler/config/outputs/validate-stats.ts
================================================
import { isOutputTargetStats, join, STATS } from '@utils';
import { isAbsolute } from 'path';
import type * as d from '../../../declarations';
export const validateStats = (userConfig: d.ValidatedConfig, userOutputs: d.OutputTarget[]) => {
const outputTargets: d.OutputTargetStats[] = [];
if (userConfig.flags.stats) {
const hasOutputTarget = userOutputs.some(isOutputTargetStats);
if (!hasOutputTarget) {
const statsOutput: d.OutputTargetStats = {
type: STATS,
};
// If --stats was provided with a path (string), use it; otherwise use default
if (typeof userConfig.flags.stats === 'string') {
statsOutput.file = userConfig.flags.stats;
}
outputTargets.push(statsOutput);
}
}
outputTargets.push(...userOutputs.filter(isOutputTargetStats));
outputTargets.forEach((outputTarget) => {
if (!outputTarget.file) {
outputTarget.file = 'stencil-stats.json';
}
if (!isAbsolute(outputTarget.file)) {
outputTarget.file = join(userConfig.rootDir, outputTarget.file);
}
});
return outputTargets;
};
================================================
FILE: src/compiler/config/outputs/validate-www.ts
================================================
import {
buildError,
COPY,
DIST_GLOBAL_STYLES,
DIST_LAZY,
isBoolean,
isOutputTargetDist,
isOutputTargetWww,
isString,
join,
WWW,
} from '@utils';
import { isAbsolute } from 'path';
import type * as d from '../../../declarations';
import { getAbsolutePath } from '../config-utils';
import { validateCopy } from '../validate-copy';
import { validatePrerender } from '../validate-prerender';
import { validateServiceWorker } from '../validate-service-worker';
export const validateWww = (config: d.ValidatedConfig, diagnostics: d.Diagnostic[], userOutputs: d.OutputTarget[]) => {
const hasOutputTargets = userOutputs.length > 0;
const hasE2eTests = !!config.flags.e2e;
const userWwwOutputs = userOutputs.filter(isOutputTargetWww);
if (
!hasOutputTargets ||
(hasE2eTests && !userOutputs.some(isOutputTargetWww) && !userOutputs.some(isOutputTargetDist))
) {
userWwwOutputs.push({ type: WWW });
}
if (config.flags.prerender && userWwwOutputs.length === 0) {
const err = buildError(diagnostics);
err.messageText = `You need at least one "www" output target configured in your stencil.config.ts, when the "--prerender" flag is used`;
}
return userWwwOutputs.reduce(
(
outputs: (d.OutputTargetWww | d.OutputTargetDistLazy | d.OutputTargetCopy | d.OutputTargetDistGlobalStyles)[],
o,
) => {
const outputTarget = validateWwwOutputTarget(config, o, diagnostics);
outputs.push(outputTarget);
// Add dist-lazy output target
const buildDir = outputTarget.buildDir;
outputs.push({
type: DIST_LAZY,
dir: buildDir,
esmDir: buildDir,
systemDir: config.buildEs5 ? buildDir : undefined,
systemLoaderFile: config.buildEs5 ? join(buildDir, `${config.fsNamespace}.js`) : undefined,
polyfills: outputTarget.polyfills,
isBrowserBuild: true,
});
// Copy for dist
outputs.push({
type: COPY,
dir: buildDir,
copyAssets: 'dist',
});
// Copy for www
outputs.push({
type: COPY,
dir: outputTarget.appDir,
copy: validateCopy(outputTarget.copy, [
{ src: 'assets', warn: false },
{ src: 'manifest.json', warn: false },
]),
});
// Generate global style with original name
outputs.push({
type: DIST_GLOBAL_STYLES,
file: join(buildDir, `${config.fsNamespace}.css`),
});
return outputs;
},
[],
);
};
const validateWwwOutputTarget = (
config: d.ValidatedConfig,
outputTarget: d.OutputTargetWww,
diagnostics: d.Diagnostic[],
) => {
if (!isString(outputTarget.baseUrl)) {
outputTarget.baseUrl = '/';
}
if (!outputTarget.baseUrl.endsWith('/')) {
// Make sure the baseUrl always finish with "/"
outputTarget.baseUrl += '/';
}
outputTarget.dir = getAbsolutePath(config, outputTarget.dir || 'www');
// Fix "dir" to account
const pathname = new URL(outputTarget.baseUrl, 'http://localhost/').pathname;
outputTarget.appDir = join(outputTarget.dir, pathname);
if (outputTarget.appDir.endsWith('/') || outputTarget.appDir.endsWith('\\')) {
outputTarget.appDir = outputTarget.appDir.substring(0, outputTarget.appDir.length - 1);
}
if (!isString(outputTarget.buildDir)) {
outputTarget.buildDir = 'build';
}
if (!isAbsolute(outputTarget.buildDir)) {
outputTarget.buildDir = join(outputTarget.appDir, outputTarget.buildDir);
}
if (!isString(outputTarget.indexHtml)) {
outputTarget.indexHtml = 'index.html';
}
if (!isAbsolute(outputTarget.indexHtml)) {
outputTarget.indexHtml = join(outputTarget.appDir, outputTarget.indexHtml);
}
if (!isBoolean(outputTarget.empty)) {
outputTarget.empty = true;
}
validatePrerender(config, diagnostics, outputTarget);
validateServiceWorker(config, outputTarget);
if (outputTarget.polyfills === undefined) {
outputTarget.polyfills = true;
}
outputTarget.polyfills = !!outputTarget.polyfills;
return outputTarget;
};
================================================
FILE: src/compiler/config/test/fixtures/stencil.config.ts
================================================
import { Config } from '../../../../declarations';
export const config: Config = {
hashedFileNameLength: 13,
};
================================================
FILE: src/compiler/config/test/fixtures/stencil.config2.ts
================================================
import { Config } from '../../../../declarations';
export const config: Config = {
hashedFileNameLength: 27,
flags: {
dev: true,
},
extras: {
enableImportInjection: true,
},
};
================================================
FILE: src/compiler/config/test/load-config.spec.ts
================================================
import { mockCompilerSystem } from '@stencil/core/testing';
import path from 'path';
import ts from 'typescript';
import { ConfigFlags } from '../../../cli/config-flags';
import type * as d from '../../../declarations';
import { normalizePath } from '../../../utils';
import { loadConfig } from '../load-config';
describe('load config', () => {
const configPath = require.resolve('./fixtures/stencil.config.ts');
const configPath2 = require.resolve('./fixtures/stencil.config2.ts');
let sys: d.CompilerSystem;
beforeEach(() => {
sys = mockCompilerSystem();
jest.spyOn(ts, 'getParsedCommandLineOfConfigFile').mockReturnValue({
options: {
target: ts.ScriptTarget.ES2017,
module: ts.ModuleKind.ESNext,
},
fileNames: [],
errors: [],
});
});
afterEach(() => {
jest.clearAllMocks();
});
it("merges a user's configuration with a stencil.config file on disk", async () => {
const loadedConfig = await loadConfig({
configPath: configPath2,
sys,
config: {
hashedFileNameLength: 9,
rootDir: '/foo/bar',
},
initTsConfig: true,
});
expect(loadedConfig.diagnostics).toHaveLength(0);
const actualConfig = loadedConfig.config;
// this field is defined on the `init` argument, and should override the value found in the config on disk
expect(actualConfig).toBeDefined();
expect(actualConfig.hashedFileNameLength).toEqual(9);
// these fields are defined in the config file on disk, and should be present
expect(actualConfig.flags).toEqual({ dev: true });
expect(actualConfig.extras).toBeDefined();
expect(actualConfig.extras!.enableImportInjection).toBe(true);
// respects custom root dir
expect(actualConfig.rootDir).toBe('/foo/bar');
});
it('uses the provided config path when no initial config provided', async () => {
const loadedConfig = await loadConfig({
configPath,
sys,
initTsConfig: true,
});
expect(loadedConfig.diagnostics).toHaveLength(0);
const actualConfig = loadedConfig.config;
expect(actualConfig).toBeDefined();
// set the config path based on the one provided in the init object
expect(actualConfig.configPath).toBe(normalizePath(configPath));
// this field is defined in the config file on disk, and should be present
expect(actualConfig.hashedFileNameLength).toBe(13);
// this field should default to an empty object literal, since it wasn't present in the config file
expect(actualConfig.flags).toEqual({});
});
describe('empty initialization argument', () => {
it('provides sensible default values with no config', async () => {
const loadedConfig = await loadConfig({ initTsConfig: true, sys });
const actualConfig = loadedConfig.config;
expect(actualConfig).toBeDefined();
expect(actualConfig.sys).toBeDefined();
expect(actualConfig.logger).toBeDefined();
expect(actualConfig.configPath).toBe(null);
});
it('creates a tsconfig file when "initTsConfig" set', async () => {
const tsconfigPath = path.resolve(path.dirname(configPath), 'tsconfig.json');
expect(sys.accessSync(tsconfigPath)).toBe(false);
const loadedConfig = await loadConfig({ initTsConfig: true, configPath, sys });
expect(sys.accessSync(tsconfigPath)).toBe(true);
expect(loadedConfig.diagnostics).toHaveLength(0);
});
it('errors that a tsconfig file could not be created when "initTsConfig" isn\'t present', async () => {
const loadedConfig = await loadConfig({ configPath, sys });
expect(loadedConfig.diagnostics).toHaveLength(1);
expect(loadedConfig.diagnostics[0]).toEqual({
absFilePath: undefined,
header: 'Missing tsconfig.json',
level: 'error',
lines: [],
messageText: `Unable to load TypeScript config file. Please create a "tsconfig.json" file within the "${normalizePath(
path.dirname(configPath),
)}" directory.`,
relFilePath: undefined,
type: 'build',
});
});
});
describe('no initialization argument', () => {
it('errors that a tsconfig file cannot be found', async () => {
const loadConfigResults = await loadConfig({ sys });
expect(loadConfigResults.diagnostics).toHaveLength(1);
expect(loadConfigResults.diagnostics[0]).toEqual({
absFilePath: undefined,
header: 'Missing tsconfig.json',
level: 'error',
lines: [],
messageText: expect.stringMatching(
`Unable to load TypeScript config file. Please create a "tsconfig.json" file within the`,
),
relFilePath: undefined,
type: 'build',
});
});
});
});
================================================
FILE: src/compiler/config/test/tsconfig.json
================================================
{
"extends": "../../../testing/tsconfig.internal.json"
}
================================================
FILE: src/compiler/config/test/validate-config-sourcemap.spec.ts
================================================
import { mockCompilerSystem, mockLoadConfigInit } from '@stencil/core/testing';
import ts from 'typescript';
import type * as d from '../../../declarations';
import { loadConfig } from '../load-config';
import { validateConfig } from '../validate-config';
describe('stencil config - sourceMap option', () => {
const configPath = require.resolve('./fixtures/stencil.config.ts');
let sys = mockCompilerSystem();
/**
* Test helper for generating default `d.LoadConfigInit` objects.
*
* This function assumes the fields in the enclosing scope have been initialized.
* @param overrides the properties on the default `d.LoadConfigInit` entity to manually override
* @returns the default configuration initialization object, with any overrides applied
*/
const getLoadConfigForTests = (overrides?: Partial): d.LoadConfigInit => {
const defaults: d.LoadConfigInit = {
configPath,
sys: sys as any,
config: {},
initTsConfig: true,
};
return mockLoadConfigInit({ ...defaults, ...overrides });
};
/**
* Test helper for mocking the {@link ts.getParsedCommandLineOfConfigFile} function. This function returns the appropriate
* `options` object based on the `sourceMap` argument.
*
* @param sourceMap The `sourceMap` option from the Stencil config.
*/
const mockTsConfigParser = (sourceMap: boolean) => {
jest.spyOn(ts, 'getParsedCommandLineOfConfigFile').mockReturnValue({
options: {
target: ts.ScriptTarget.ES2017,
module: ts.ModuleKind.ESNext,
sourceMap,
inlineSources: sourceMap,
},
fileNames: [],
errors: [],
});
};
beforeEach(() => {
sys = mockCompilerSystem();
});
afterEach(() => {
jest.clearAllMocks();
});
it('sets sourceMap to true when explicitly set to true', async () => {
const userConfig: d.UnvalidatedConfig = { sourceMap: true };
const { config: validatedConfig } = validateConfig(userConfig, {});
expect(validatedConfig.sourceMap).toBe(true);
mockTsConfigParser(validatedConfig.sourceMap);
const testConfig = getLoadConfigForTests({ config: userConfig });
const loadConfigResults = await loadConfig(testConfig);
const { sourceMap, inlineSources } = loadConfigResults.config.tsCompilerOptions;
expect(sourceMap).toBe(true);
expect(inlineSources).toBe(true);
});
it('sets sourceMap to false when explicitly set to false', async () => {
const userConfig: d.UnvalidatedConfig = { sourceMap: false };
const { config: validatedConfig } = validateConfig(userConfig, {});
expect(validatedConfig.sourceMap).toBe(false);
mockTsConfigParser(validatedConfig.sourceMap);
const testConfig = getLoadConfigForTests({ config: userConfig });
const loadConfigResults = await loadConfig(testConfig);
const { sourceMap, inlineSources } = loadConfigResults.config.tsCompilerOptions;
expect(sourceMap).toBe(false);
expect(inlineSources).toBe(false);
});
it('defaults to "dev" behavior (false in prod mode)', async () => {
const userConfig: d.UnvalidatedConfig = { devMode: false };
const { config: validatedConfig } = validateConfig(userConfig, {});
expect(validatedConfig.sourceMap).toBe(false);
mockTsConfigParser(validatedConfig.sourceMap);
const testConfig = getLoadConfigForTests({ config: userConfig });
const loadConfigResults = await loadConfig(testConfig);
const { sourceMap, inlineSources } = loadConfigResults.config.tsCompilerOptions;
expect(sourceMap).toBe(false);
expect(inlineSources).toBe(false);
});
it('defaults to "dev" behavior (true in dev mode)', async () => {
const userConfig: d.UnvalidatedConfig = { devMode: true };
const { config: validatedConfig } = validateConfig(userConfig, {});
expect(validatedConfig.sourceMap).toBe(true);
mockTsConfigParser(validatedConfig.sourceMap);
const testConfig = getLoadConfigForTests({ config: userConfig });
const loadConfigResults = await loadConfig(testConfig);
const { sourceMap, inlineSources } = loadConfigResults.config.tsCompilerOptions;
expect(sourceMap).toBe(true);
expect(inlineSources).toBe(true);
});
it('resolves "dev" to true when devMode is true', async () => {
const userConfig: d.UnvalidatedConfig = { sourceMap: 'dev', devMode: true };
const { config: validatedConfig } = validateConfig(userConfig, {});
expect(validatedConfig.sourceMap).toBe(true);
mockTsConfigParser(validatedConfig.sourceMap);
const testConfig = getLoadConfigForTests({ config: userConfig });
const loadConfigResults = await loadConfig(testConfig);
const { sourceMap, inlineSources } = loadConfigResults.config.tsCompilerOptions;
expect(sourceMap).toBe(true);
expect(inlineSources).toBe(true);
});
it('resolves "dev" to false when devMode is false', async () => {
const userConfig: d.UnvalidatedConfig = { sourceMap: 'dev', devMode: false };
const { config: validatedConfig } = validateConfig(userConfig, {});
expect(validatedConfig.sourceMap).toBe(false);
mockTsConfigParser(validatedConfig.sourceMap);
const testConfig = getLoadConfigForTests({ config: userConfig });
const loadConfigResults = await loadConfig(testConfig);
const { sourceMap, inlineSources } = loadConfigResults.config.tsCompilerOptions;
expect(sourceMap).toBe(false);
expect(inlineSources).toBe(false);
});
});
================================================
FILE: src/compiler/config/test/validate-config.spec.ts
================================================
import type * as d from '@stencil/core/declarations';
import { mockCompilerSystem, mockLoadConfigInit, mockLogger } from '@stencil/core/testing';
import { DOCS_CUSTOM, DOCS_JSON, DOCS_README, DOCS_VSCODE } from '@utils';
import { createConfigFlags } from '../../../cli/config-flags';
import { isWatchIgnorePath } from '../../fs-watch/fs-watch-rebuild';
import { validateConfig } from '../validate-config';
describe('validation', () => {
let userConfig: d.UnvalidatedConfig;
let bootstrapConfig: d.LoadConfigInit;
const logger = mockLogger();
const sys = mockCompilerSystem();
beforeEach(() => {
userConfig = {
sys: sys,
logger: logger,
rootDir: '/User/some/path/',
namespace: 'Testing',
};
bootstrapConfig = mockLoadConfigInit();
});
describe('caching', () => {
it('should cache the validated config between calls if the same config is passed back in', () => {
const { config } = validateConfig(userConfig, {});
const { config: secondRound } = validateConfig(config, {});
// we should have object identity
expect(config === secondRound).toBe(true);
// objects should be deepEqual as well
expect(config).toEqual(secondRound);
});
it('should bust the cache if a different config is supplied than the cached one', () => {
// validate once, caching that result
const { config } = validateConfig(userConfig, {});
// pass a new initial configuration
const { config: secondRound } = validateConfig({ ...userConfig }, {});
// shouldn't have object equality with the earlier one
expect(config === secondRound).toBe(false);
});
});
describe('flags', () => {
it('adds a default "flags" object if none is provided', () => {
userConfig.flags = undefined;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.flags).toEqual({});
});
it('serializes a provided "flags" object', () => {
userConfig.flags = createConfigFlags({ dev: false });
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.flags).toEqual(createConfigFlags({ dev: false }));
});
describe('devMode', () => {
it('defaults "devMode" to false when "flag.prod" is truthy', () => {
userConfig.flags = createConfigFlags({ prod: true });
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.devMode).toBe(false);
});
it('defaults "devMode" to true when "flag.dev" is truthy', () => {
userConfig.flags = createConfigFlags({ dev: true });
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.devMode).toBe(true);
});
it('defaults "devMode" to false when "flag.prod" & "flag.dev" are truthy', () => {
userConfig.flags = createConfigFlags({ dev: true, prod: true });
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.devMode).toBe(false);
});
it('sets "devMode" to false if the user provided flag isn\'t a boolean', () => {
// the branch under test explicitly requires a value whose type is not allowed by the type system
const devMode = 'not-a-bool' as unknown as boolean;
userConfig = { devMode };
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.devMode).toBe(false);
});
});
});
describe('allowInlineScripts', () => {
it('set allowInlineScripts true', () => {
userConfig.allowInlineScripts = true;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.allowInlineScripts).toBe(true);
});
it('set allowInlineScripts false', () => {
userConfig.allowInlineScripts = false;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.allowInlineScripts).toBe(false);
});
it('default allowInlineScripts true', () => {
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.allowInlineScripts).toBe(true);
});
});
describe('transformAliasedImportPaths', () => {
it.each([true, false])('set transformAliasedImportPaths %p', (bool) => {
userConfig.transformAliasedImportPaths = bool;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.transformAliasedImportPaths).toBe(bool);
});
it('defaults `transformAliasedImportPaths` to true', () => {
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.transformAliasedImportPaths).toBe(true);
});
});
describe('suppressReservedPublicNameWarnings', () => {
it.each([true, false])('sets suppressReservedPublicNameWarnings to %p when provided', (bool) => {
userConfig.suppressReservedPublicNameWarnings = bool;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.suppressReservedPublicNameWarnings).toBe(bool);
});
it('defaults suppressReservedPublicNameWarnings to false', () => {
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.suppressReservedPublicNameWarnings).toBe(false);
});
});
describe('enableCache', () => {
it('set enableCache true', () => {
userConfig.enableCache = true;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.enableCache).toBe(true);
});
it('set enableCache false', () => {
userConfig.enableCache = false;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.enableCache).toBe(false);
});
it('default enableCache true', () => {
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.enableCache).toBe(true);
});
});
describe('buildAppCore', () => {
it('set buildAppCore true', () => {
userConfig.buildAppCore = true;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.buildAppCore).toBe(true);
});
it('set buildAppCore false', () => {
userConfig.buildAppCore = false;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.buildAppCore).toBe(false);
});
it('default buildAppCore true', () => {
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.buildAppCore).toBe(true);
});
});
describe('es5 build', () => {
it('set buildEs5 false', () => {
userConfig.buildEs5 = false;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.buildEs5).toBe(false);
});
it('set buildEs5 true', () => {
userConfig.buildEs5 = true;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.buildEs5).toBe(true);
});
it('set buildEs5 true, dev mode', () => {
userConfig.devMode = true;
userConfig.buildEs5 = true;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.buildEs5).toBe(true);
});
it('prod mode, set modern and es5', () => {
userConfig.devMode = false;
userConfig.buildEs5 = true;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.buildEs5).toBe(true);
});
it('build es5 when set to "prod" and in prod', () => {
userConfig.devMode = false;
userConfig.buildEs5 = 'prod';
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.buildEs5).toBe(true);
});
it('do not build es5 when set to "prod" and in dev', () => {
userConfig.devMode = true;
userConfig.buildEs5 = 'prod';
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.buildEs5).toBe(false);
});
it('prod mode default to only modern and not es5', () => {
userConfig.devMode = false;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.buildEs5).toBe(false);
});
});
describe('hashed filenames', () => {
it('should error when hashedFileNameLength too large', () => {
userConfig.hashedFileNameLength = 33;
const validated = validateConfig(userConfig, bootstrapConfig);
expect(validated.diagnostics).toHaveLength(1);
});
it('should error when hashedFileNameLength too small', () => {
userConfig.hashedFileNameLength = 3;
const validated = validateConfig(userConfig, bootstrapConfig);
expect(validated.diagnostics).toHaveLength(1);
});
it('should set from hashedFileNameLength', () => {
userConfig.hashedFileNameLength = 28;
const validated = validateConfig(userConfig, bootstrapConfig);
expect(validated.config.hashedFileNameLength).toBe(28);
});
it('should set hashedFileNameLength', () => {
userConfig.hashedFileNameLength = 6;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.hashedFileNameLength).toBe(6);
});
it('should default hashedFileNameLength', () => {
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.hashedFileNameLength).toBe(8);
});
it('should default hashFileNames to false in watch mode despite prod mode', () => {
userConfig.watch = true;
userConfig.devMode = false;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.hashFileNames).toBe(true);
});
it('should default hashFileNames to true in prod mode', () => {
userConfig.devMode = false;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.hashFileNames).toBe(true);
});
it('should default hashFileNames to false in dev mode', () => {
userConfig.devMode = true;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.hashFileNames).toBe(false);
});
it.each([true, false])('should set hashFileNames when hashFileNames===%b', (hashFileNames) => {
userConfig.hashFileNames = hashFileNames;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.hashFileNames).toBe(hashFileNames);
});
it('should set hashFileNames from function', () => {
(userConfig as any).hashFileNames = () => {
return true;
};
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.hashFileNames).toBe(true);
});
});
describe('minifyJs', () => {
it('should set minifyJs to true', () => {
userConfig.devMode = true;
userConfig.minifyJs = true;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.minifyJs).toBe(true);
});
it('should default minifyJs to true in prod mode', () => {
userConfig.devMode = false;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.minifyJs).toBe(true);
});
it('should default minifyJs to false in dev mode', () => {
userConfig.devMode = true;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.minifyJs).toBe(false);
});
});
describe('minifyCss', () => {
it('should set minifyCss to true', () => {
userConfig.devMode = true;
userConfig.minifyCss = true;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.minifyCss).toBe(true);
});
it('should default minifyCss to true in prod mode', () => {
userConfig.devMode = false;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.minifyCss).toBe(true);
});
it('should default minifyCss to false in dev mode', () => {
userConfig.devMode = true;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.minifyCss).toBe(false);
});
});
it('should default watch to false', () => {
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.watch).toBe(false);
});
it('should set devMode to false', () => {
userConfig.devMode = false;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.devMode).toBe(false);
});
it('should set devMode to true', () => {
userConfig.devMode = true;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.devMode).toBe(true);
});
it('should default devMode to false', () => {
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.devMode).toBe(false);
});
it.each([DOCS_JSON, DOCS_CUSTOM, DOCS_README, DOCS_VSCODE])(
'should not add "%s" output target by default',
(targetType) => {
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.outputTargets.some((o) => o.type === targetType)).toBe(false);
},
);
it('should set devInspector false', () => {
userConfig.devInspector = false;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.devInspector).toBe(false);
});
it('should set devInspector true', () => {
userConfig.devInspector = true;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.devInspector).toBe(true);
});
it('should default devInspector false when devMode is false', () => {
userConfig.devMode = false;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.devInspector).toBe(false);
});
it('should default devInspector true when devMode is true', () => {
userConfig.devMode = true;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.devInspector).toBe(true);
});
it('should default dist false and www true', () => {
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.outputTargets.some((o) => o.type === 'dist')).toBe(false);
expect(config.outputTargets.some((o) => o.type === 'www')).toBe(true);
});
it('should error for invalid outputTarget type', () => {
userConfig.outputTargets = [
{
type: 'whatever',
} as any,
];
const validated = validateConfig(userConfig, bootstrapConfig);
expect(validated.diagnostics).toHaveLength(1);
});
it('should default outputTargets with www', () => {
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.outputTargets.some((o) => o.type === 'www')).toBe(true);
});
it('should set extras defaults', () => {
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.extras.appendChildSlotFix).toBe(false);
expect(config.extras.cloneNodeFix).toBe(false);
expect(config.extras.lifecycleDOMEvents).toBe(false);
expect(config.extras.scriptDataOpts).toBe(false);
expect(config.extras.slotChildNodesFix).toBe(false);
expect(config.extras.initializeNextTick).toBe(false);
expect(config.extras.tagNameTransform).toBe(false);
expect(config.extras.additionalTagTransformers).toBe(false);
expect(config.extras.scopedSlotTextContentFix).toBe(false);
expect(config.extras.addGlobalStyleToComponents).toBe('client');
expect(config.extras.additionalTagTransformers).toBe(false);
});
describe('extras.additionalTagTransformers', () => {
it('set extras.additionalTagTransformers false', () => {
userConfig.extras = { additionalTagTransformers: false };
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.extras.additionalTagTransformers).toBe(false);
});
it('set extras.additionalTagTransformers true', () => {
userConfig.extras = { additionalTagTransformers: true };
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.extras.additionalTagTransformers).toBe(true);
});
it('set extras.additionalTagTransformers true, dev mode', () => {
userConfig.devMode = true;
userConfig.extras = { additionalTagTransformers: true };
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.extras.additionalTagTransformers).toBe(true);
});
it('prod mode, set extras.additionalTagTransformers', () => {
userConfig.devMode = false;
userConfig.extras = { additionalTagTransformers: true };
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.extras.additionalTagTransformers).toBe(true);
});
it('build extras.additionalTagTransformers when set to "prod" and in prod', () => {
userConfig.devMode = false;
userConfig.extras = { additionalTagTransformers: 'prod' };
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.extras.additionalTagTransformers).toBe(true);
});
it('do not build extras.additionalTagTransformers when set to "prod" and in dev', () => {
userConfig.devMode = true;
userConfig.extras = { additionalTagTransformers: 'prod' };
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.extras.additionalTagTransformers).toBe(false);
});
it('prod mode default to only modern and not extras.additionalTagTransformers', () => {
userConfig.devMode = false;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.extras.additionalTagTransformers).toBe(false);
});
});
it('should set slot config based on `experimentalSlotFixes`', () => {
userConfig.extras = {};
userConfig.extras.experimentalSlotFixes = true;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.extras.appendChildSlotFix).toBe(true);
expect(config.extras.cloneNodeFix).toBe(true);
expect(config.extras.slotChildNodesFix).toBe(true);
expect(config.extras.scopedSlotTextContentFix).toBe(true);
});
it('should override slot fix config based on `experimentalSlotFixes`', () => {
// This test is to verify the flags get overwritten correctly even if an
// invalid config is ingested. Hence, the `any` cast
userConfig.extras = {
appendChildSlotFix: false,
slotChildNodesFix: false,
cloneNodeFix: false,
scopedSlotTextContentFix: false,
experimentalSlotFixes: true,
} as any;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.extras.appendChildSlotFix).toBe(true);
expect(config.extras.cloneNodeFix).toBe(true);
expect(config.extras.slotChildNodesFix).toBe(true);
expect(config.extras.scopedSlotTextContentFix).toBe(true);
});
it('should set extras experimentalScopedSlotChanges `true` if set in user config', () => {
userConfig.extras = {
experimentalScopedSlotChanges: true,
};
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.extras.experimentalScopedSlotChanges).toBe(true);
});
it('should set taskQueue "async" by default', () => {
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.taskQueue).toBe('async');
});
it('should set taskQueue', () => {
userConfig.taskQueue = 'congestionAsync';
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.taskQueue).toBe('congestionAsync');
});
it('empty watchIgnoredRegex, all valid', () => {
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.watchIgnoredRegex).toEqual([]);
expect(isWatchIgnorePath(config, '/some/image.gif')).toBe(false);
expect(isWatchIgnorePath(config, '/some/typescript.ts')).toBe(false);
});
it('should change a single watchIgnoredRegex to an array', () => {
userConfig.watchIgnoredRegex = /\.(gif|jpe?g|png)$/i;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.watchIgnoredRegex).toHaveLength(1);
expect((config.watchIgnoredRegex as any[])[0]).toEqual(/\.(gif|jpe?g|png)$/i);
expect(isWatchIgnorePath(config, '/some/image.gif')).toBe(true);
expect(isWatchIgnorePath(config, '/some/typescript.ts')).toBe(false);
});
it('should clean up valid watchIgnoredRegex', () => {
userConfig.watchIgnoredRegex = [/\.(gif|jpe?g)$/i, null, 'me-regex' as any, /\.(png)$/i];
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.watchIgnoredRegex).toHaveLength(2);
expect((config.watchIgnoredRegex as any[])[0]).toEqual(/\.(gif|jpe?g)$/i);
expect((config.watchIgnoredRegex as any[])[1]).toEqual(/\.(png)$/i);
expect(isWatchIgnorePath(config, '/some/image.gif')).toBe(true);
expect(isWatchIgnorePath(config, '/some/image.jpg')).toBe(true);
expect(isWatchIgnorePath(config, '/some/image.png')).toBe(true);
expect(isWatchIgnorePath(config, '/some/typescript.ts')).toBe(false);
});
describe('sourceMap', () => {
it('sets the field to true when the set to true in the config', () => {
userConfig.sourceMap = true;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.sourceMap).toBe(true);
});
it('sets the field to false when set to false in the config', () => {
userConfig.sourceMap = false;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.sourceMap).toBe(false);
});
it('defaults to "dev" behavior when not set (true in dev mode)', () => {
userConfig.devMode = true;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.sourceMap).toBe(true);
});
it('defaults to "dev" behavior when not set (false in prod mode)', () => {
userConfig.devMode = false;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.sourceMap).toBe(false);
});
it('sets the field to true when set to "dev" and devMode is true', () => {
userConfig.sourceMap = 'dev';
userConfig.devMode = true;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.sourceMap).toBe(true);
});
it('sets the field to false when set to "dev" and devMode is false', () => {
userConfig.sourceMap = 'dev';
userConfig.devMode = false;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.sourceMap).toBe(false);
});
it('sets the field to true when set to "dev" and --dev flag is passed', () => {
userConfig.sourceMap = 'dev';
userConfig.flags = createConfigFlags({ dev: true });
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.sourceMap).toBe(true);
});
it('sets the field to false when set to "dev" and --prod flag is passed', () => {
userConfig.sourceMap = 'dev';
userConfig.flags = createConfigFlags({ prod: true });
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.sourceMap).toBe(false);
});
});
describe('buildDist', () => {
it.each([true, false])('should set the field based on the config flag (%p)', (flag) => {
userConfig.flags = createConfigFlags({ esm: flag });
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.buildDist).toBe(flag);
});
it.each([true, false])('should fallback to !devMode', (devMode) => {
userConfig.devMode = devMode;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.buildDist).toBe(!devMode);
});
it.each([true, false])('should fallback to buildEs5 in devMode', (buildEs5) => {
userConfig.devMode = true;
userConfig.buildEs5 = buildEs5;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.buildDist).toBe(config.buildEs5);
});
});
describe('validatePrimaryPackageOutputTarget', () => {
it('should default to false', () => {
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.validatePrimaryPackageOutputTarget).toBe(false);
});
it.each([true, false])(
'should set validatePrimaryPackageOutputTarget to %p',
(validatePrimaryPackageOutputTarget) => {
userConfig.validatePrimaryPackageOutputTarget = validatePrimaryPackageOutputTarget;
const { config } = validateConfig(userConfig, bootstrapConfig);
expect(config.validatePrimaryPackageOutputTarget).toBe(validatePrimaryPackageOutputTarget);
},
);
});
});
================================================
FILE: src/compiler/config/test/validate-copy.spec.ts
================================================
import type * as d from '../../../declarations';
import { validateCopy } from '../validate-copy';
describe('validate-copy', () => {
describe('validateCopy', () => {
it.each([false, null, undefined, []])('returns an empty array when the copy task is `%s`', (copyValue) => {
expect(validateCopy(copyValue, [])).toEqual([]);
});
it('pushes default tasks not found in the original copy list', () => {
const defaultCopyTasks: d.CopyTask[] = [
{ src: 'defaultSrc' },
{ src: 'anotherDefaultSrc', dest: 'anotherDefaultDest' },
];
expect(validateCopy([], defaultCopyTasks)).toEqual(defaultCopyTasks);
});
it('combines provided and default tasks', () => {
const tasksToValidate: d.CopyTask[] = [{ src: 'someSrc', dest: 'someDest', keepDirStructure: true, warn: false }];
const defaultCopyTasks: d.CopyTask[] = [
{ src: 'defaultSrc' },
{ src: 'anotherDefaultSrc', dest: 'anotherDefaultDest' },
];
expect(validateCopy(tasksToValidate, defaultCopyTasks)).toEqual([...tasksToValidate, ...defaultCopyTasks]);
});
it('prefers provided tasks over default tasks', () => {
const tasksToValidate: d.CopyTask[] = [
{ src: 'aDuplicateSrc', dest: 'someDest', keepDirStructure: true, warn: false },
];
const defaultCopyTasks: d.CopyTask[] = [
{ src: 'aDuplicateSrc' },
{ src: 'anotherDefaultSrc', dest: 'anotherDefaultDest' },
];
// the first task from the default task list is not used
expect(validateCopy(tasksToValidate, defaultCopyTasks)).toEqual([
{ src: 'aDuplicateSrc', dest: 'someDest', keepDirStructure: true, warn: false },
{ src: 'anotherDefaultSrc', dest: 'anotherDefaultDest' },
]);
});
it('de-duplicates copy tasks', () => {
const copyTask: d.CopyTask = { src: 'aDuplicateSrc', dest: 'someDest', keepDirStructure: true, warn: false };
const tasksToValidate: d.CopyTask[] = [{ ...copyTask }, { ...copyTask }];
expect(validateCopy(tasksToValidate, [])).toEqual([{ ...copyTask }]);
});
});
});
================================================
FILE: src/compiler/config/test/validate-custom.spec.ts
================================================
import type * as d from '@stencil/core/declarations';
import { mockConfig, mockLoadConfigInit } from '@stencil/core/testing';
import { buildWarn } from '@utils';
import { validateConfig } from '../validate-config';
describe('validateCustom', () => {
let userConfig: d.Config;
beforeEach(() => {
userConfig = mockConfig();
});
it('should log warning', () => {
userConfig.outputTargets = [
{
type: 'custom',
name: 'test',
validate: (_, diagnostics) => {
const warn = buildWarn(diagnostics);
warn.messageText = 'test warning';
},
generator: async () => {
return;
},
},
];
const { diagnostics } = validateConfig(userConfig, mockLoadConfigInit());
// TODO(STENCIL-1107): Decrement the right-hand side value from 2 to 1
expect(diagnostics.length).toBe(2);
// TODO(STENCIL-1107): Keep this assertion
expect(diagnostics[0]).toEqual({
header: 'Build Warn',
level: 'warn',
lines: [],
messageText: 'test warning',
type: 'build',
});
// TODO(STENCIL-1107): Remove this assertion
expect(diagnostics[1]).toEqual({
header: 'Build Warn',
level: 'warn',
lines: [],
messageText:
'nodeResolve.customResolveOptions is a deprecated option in a Stencil Configuration file. If you need this option, please open a new issue in the Stencil repository (https://github.com/stenciljs/core/issues/new/choose)',
type: 'build',
});
});
});
================================================
FILE: src/compiler/config/test/validate-dev-server.spec.ts
================================================
import { mockLoadConfigInit } from '@stencil/core/testing';
import path from 'path';
import { ConfigFlags, createConfigFlags } from '../../../cli/config-flags';
import type * as d from '../../../declarations';
import { normalizePath } from '../../../utils';
import { validateConfig } from '../validate-config';
describe('validateDevServer', () => {
const root = path.resolve('/');
let inputConfig: d.UnvalidatedConfig;
let inputDevServerConfig: d.DevServerConfig;
let flags: ConfigFlags;
beforeEach(() => {
inputDevServerConfig = {};
flags = createConfigFlags({ serve: true });
inputConfig = {
sys: {} as any,
rootDir: normalizePath(path.join(root, 'some', 'path')),
devServer: inputDevServerConfig,
flags,
namespace: 'Testing',
};
});
it('should default address', () => {
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.address).toBe('0.0.0.0');
});
it.each(['https://localhost', 'http://localhost', 'https://localhost/', 'http://localhost/', 'localhost/'])(
'should remove extraneous stuff from address %p',
(address) => {
inputConfig.devServer = { ...inputDevServerConfig, address };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.address).toBe('localhost');
},
);
it('should set address', () => {
inputConfig.devServer = { ...inputDevServerConfig, address: '123.123.123.123' };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.address).toBe('123.123.123.123');
});
it('should set address from flags', () => {
inputConfig.flags = { ...flags, address: '123.123.123.123' };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.address).toBe('123.123.123.123');
});
it('should get custom baseUrl', () => {
inputConfig.outputTargets = [
{
type: 'www',
baseUrl: '/my-base-url',
} as d.OutputTargetWww,
];
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.basePath).toBe('/my-base-url/');
});
it('should get custom baseUrl with domain', () => {
inputConfig.outputTargets = [
{
type: 'www',
baseUrl: 'http://stenciljs.com/my-base-url',
} as d.OutputTargetWww,
];
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.basePath).toBe('/my-base-url/');
});
it('should default basePath', () => {
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.basePath).toBe('/');
});
it('should default root', () => {
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.root).toBe(normalizePath(path.join(root, 'some', 'path', 'www')));
});
it('should set relative root', () => {
inputConfig.devServer = { ...inputDevServerConfig, root: 'my-rel-root' };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.root).toBe(normalizePath(path.join(root, 'some', 'path', 'my-rel-root')));
});
it('should set absolute root', () => {
inputConfig.devServer = {
...inputDevServerConfig,
root: normalizePath(path.join(root, 'some', 'path', 'my-abs-root')),
};
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.root).toBe(normalizePath(path.join(root, 'some', 'path', 'my-abs-root')));
});
it('should default gzip', () => {
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.gzip).toBe(true);
});
it('should set gzip', () => {
inputConfig.devServer = { ...inputDevServerConfig, gzip: false };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.gzip).toBe(false);
});
it.each(['localhost', '192.12.12.10', '127.0.0.1'])('should default port with address %p', () => {
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.port).toBe(3333);
});
it.each(['https://subdomain.stenciljs.com:3000', 'localhost:3000/', 'localhost:3000'])(
'should override port in address with port property',
(address) => {
inputConfig.devServer = { ...inputDevServerConfig, address, port: 1234 };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.port).toBe(1234);
},
);
it('should not set default port if null', () => {
// we intentionally set the value to `null` for the purposes of this test, hence the type assertion
inputConfig.devServer = { ...inputDevServerConfig, port: null as unknown as number };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.port).toBe(null);
});
it('sets the port to 3333 if the port is undefined', () => {
inputConfig.devServer = { ...inputDevServerConfig, port: undefined };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.port).toBe(3333);
});
it.each(['localhost:20/', 'localhost:20'])('should set port from address %p if no port prop', (address) => {
inputConfig.devServer = { ...inputDevServerConfig, address };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.port).toBe(20);
expect(config.devServer.address).toBe('localhost');
});
it('should set address, port null, protocol', () => {
inputConfig.devServer = { ...inputDevServerConfig, address: 'https://subdomain.stenciljs.com/' };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.port).toBe(undefined);
expect(config.devServer.address).toBe('subdomain.stenciljs.com');
expect(config.devServer.protocol).toBe('https');
});
it('should set port', () => {
inputConfig.devServer = { ...inputDevServerConfig, port: 4444 };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.port).toBe(4444);
});
it('should set port from flags', () => {
inputConfig.flags = { ...flags, port: 4444 };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.port).toBe(4444);
});
it('should default strictPort to false', () => {
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.strictPort).toBe(false);
});
it('should set strictPort to true', () => {
inputConfig.devServer = { ...inputDevServerConfig, strictPort: true };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.strictPort).toBe(true);
});
it('should set strictPort to false', () => {
inputConfig.devServer = { ...inputDevServerConfig, strictPort: false };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.strictPort).toBe(false);
});
it('should default historyApiFallback', () => {
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.historyApiFallback).toBeDefined();
expect(config.devServer.historyApiFallback!.index).toBe('index.html');
});
it.each([1, []])('should default historyApiFallback when an invalid value (%s) is provided', (badValue) => {
// this test explicitly checks for a bad value in the stencil.config file, hence the type assertion
inputConfig.devServer = { ...inputDevServerConfig, historyApiFallback: badValue as any };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.historyApiFallback).toBeDefined();
expect(config.devServer.historyApiFallback!.index).toBe('index.html');
});
it('should set historyApiFallback', () => {
inputConfig.devServer = { ...inputDevServerConfig, historyApiFallback: {} };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.historyApiFallback).toBeDefined();
expect(config.devServer.historyApiFallback!.index).toBe('index.html');
});
it('should sets the historyApiFallback when undefined is provided', () => {
inputConfig.devServer = { ...inputDevServerConfig, historyApiFallback: undefined };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.historyApiFallback).toBeDefined();
expect(config.devServer.historyApiFallback!.disableDotRule).toBe(false);
expect(config.devServer.historyApiFallback!.index).toBe('index.html');
});
it('should disable historyApiFallback', () => {
// we intentionally set the value to `null` for the purposes of this test, hence the type assertion
inputConfig.devServer = { ...inputDevServerConfig, historyApiFallback: null as unknown as d.HistoryApiFallback };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.historyApiFallback).toBe(null);
});
it('should default reloadStrategy hmr', () => {
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.reloadStrategy).toBe('hmr');
});
it('should set reloadStrategy pageReload', () => {
inputConfig.devServer = { ...inputDevServerConfig, reloadStrategy: 'pageReload' };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.reloadStrategy).toBe('pageReload');
});
it('should default openBrowser', () => {
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.openBrowser).toBe(true);
});
it('should set openBrowser', () => {
inputConfig.devServer = { ...inputDevServerConfig, openBrowser: false };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.openBrowser).toBe(false);
});
it('should set openBrowser from flag', () => {
// the flags field should have been set up in the `beforeEach` block for this test, hence the bang operator
inputConfig.flags!.open = false;
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.openBrowser).toBe(false);
});
it('should default http protocol', () => {
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.protocol).toBe('http');
});
it('should set https protocol if credentials are set', () => {
inputConfig.devServer = { ...inputDevServerConfig, https: { key: 'fake-key', cert: 'fake-cert' } };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.protocol).toBe('https');
});
it('should set ssr true', () => {
inputConfig.devServer = { ssr: true };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.ssr).toBe(true);
});
it('should set ssr false', () => {
inputConfig.devServer = { ssr: false };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.ssr).toBe(false);
});
it('should set ssr from flag', () => {
inputConfig.flags = { ...flags, ssr: true };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.ssr).toBe(true);
});
it('should set ssr false by default', () => {
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.ssr).toBe(false);
});
it('should set default srcIndexHtml from config', () => {
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.srcIndexHtml).toBe(normalizePath(path.join(root, 'some', 'path', 'src', 'index.html')));
});
it('should set srcIndexHtml from config', () => {
const wwwOutputTarget: d.OutputTargetWww = {
type: 'www',
prerenderConfig: normalizePath(path.join(root, 'some', 'path', 'prerender.config.ts')),
};
inputConfig.outputTargets = [wwwOutputTarget];
inputConfig.flags = { ...flags, ssr: true };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.prerenderConfig).toBe(wwwOutputTarget.prerenderConfig);
});
describe('pingRoute', () => {
it('should default to /ping', () => {
// Ensure the pingRoute is not set in the inputConfig so we know we're testing the
// default value added during validation
delete inputConfig.devServer.pingRoute;
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.pingRoute).toBe('/ping');
});
it('should set user defined pingRoute', () => {
inputConfig.devServer = { ...inputDevServerConfig, pingRoute: '/my-ping' };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.pingRoute).toBe('/my-ping');
});
it('should prefix pingRoute with a "/"', () => {
inputConfig.devServer = { ...inputDevServerConfig, pingRoute: 'my-ping' };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.pingRoute).toBe('/my-ping');
});
it('should clear ping route if set to null', () => {
inputConfig.devServer = { ...inputDevServerConfig, pingRoute: null };
const { config } = validateConfig(inputConfig, mockLoadConfigInit());
expect(config.devServer.pingRoute).toBe(null);
});
});
});
================================================
FILE: src/compiler/config/test/validate-docs.spec.ts
================================================
import type * as d from '@stencil/core/declarations';
import { mockConfig, mockLoadConfigInit } from '@stencil/core/testing';
import { DEFAULT_TARGET_COMPONENT_STYLES } from '../constants';
import { validateConfig } from '../validate-config';
describe('validateDocs', () => {
let userConfig: d.Config;
beforeEach(() => {
userConfig = mockConfig();
});
it('readme docs dir', () => {
// the flags field is expected to have been set by the mock creation function for unvalidated configs, hence the
// bang operator
userConfig.flags!.docs = true;
userConfig.outputTargets = [
{
type: 'docs-readme',
dir: 'my-dir',
} as d.OutputTargetDocsReadme,
];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
const o = config.outputTargets.find((o) => o.type === 'docs-readme') as d.OutputTargetDocsReadme;
expect(o.dir).toContain('my-dir');
});
it('default no docs, not remove docs output target', () => {
userConfig.outputTargets = [{ type: 'docs-readme' }];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets.some((o) => o.type === 'docs-readme')).toBe(true);
});
it('default no docs, no output target', () => {
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets.some((o) => o.type === 'docs-readme')).toBe(false);
});
it('should use default values for docs.markdown.targetComponent', () => {
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.docs.markdown.targetComponent.background).toBe(DEFAULT_TARGET_COMPONENT_STYLES.background);
});
it('should use user values for docs.markdown.targetComponent.background', () => {
userConfig = mockConfig({
docs: {
markdown: {
targetComponent: {
background: '#123',
},
},
},
});
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.docs.markdown.targetComponent.background).toBe(userConfig.docs.markdown.targetComponent.background);
});
it('should use user values for docs.markdown.targetComponent.textColor', () => {
userConfig = mockConfig({
docs: {
markdown: {
targetComponent: {
textColor: '#123',
},
},
},
});
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.docs.markdown.targetComponent.textColor).toBe(userConfig.docs.markdown.targetComponent.textColor);
});
});
================================================
FILE: src/compiler/config/test/validate-hydrated.spec.ts
================================================
import * as d from '@stencil/core/declarations';
import { validateHydrated } from '../validate-hydrated';
describe('validate-hydrated', () => {
describe('validateHydrated', () => {
let inputConfig: d.UnvalidatedConfig;
let inputHydrateFlagConfig: d.HydratedFlag;
beforeEach(() => {
inputHydrateFlagConfig = {};
inputConfig = {
hydratedFlag: inputHydrateFlagConfig,
};
});
it.each([null, false])('returns undefined for hydratedFlag=%s', (badValue) => {
// this test explicitly checks for a bad value in the stencil.config file, hence the type assertion
(inputConfig.hydratedFlag as any) = badValue;
const actual = validateHydrated(inputConfig);
expect(actual).toBeNull();
});
it.each([[], true])('returns a default value when hydratedFlag=%s', (badValue) => {
// this test explicitly checks for a bad value in the stencil.config file, hence the type assertion
(inputConfig.hydratedFlag as any) = badValue;
const actual = validateHydrated(inputConfig);
expect(actual).toEqual({
hydratedValue: 'inherit',
initialValue: 'hidden',
name: 'hydrated',
property: 'visibility',
selector: 'class',
});
});
});
});
================================================
FILE: src/compiler/config/test/validate-namespace.spec.ts
================================================
import type * as d from '@stencil/core/declarations';
import { validateNamespace } from '../validate-namespace';
// TODO(STENCIL-968): Update tests to check diagnostic messages
describe('validateNamespace', () => {
const diagnostics: d.Diagnostic[] = [];
beforeEach(() => {
diagnostics.length = 0;
});
it('should not allow special characters in namespace', () => {
validateNamespace('My/Namespace', undefined, diagnostics);
expect(diagnostics).toHaveLength(1);
diagnostics.length = 0;
validateNamespace('My%20Namespace', undefined, diagnostics);
expect(diagnostics).toHaveLength(1);
diagnostics.length = 0;
validateNamespace('My:Namespace', undefined, diagnostics);
expect(diagnostics).toHaveLength(1);
});
it('should not allow spaces in namespace', () => {
validateNamespace('My Namespace', undefined, diagnostics);
expect(diagnostics).toHaveLength(1);
});
it('should not allow dash for last character of namespace', () => {
validateNamespace('MyNamespace-', undefined, diagnostics);
expect(diagnostics).toHaveLength(1);
});
it('should not allow dash for first character of namespace', () => {
validateNamespace('-MyNamespace', undefined, diagnostics);
expect(diagnostics).toHaveLength(1);
});
it('should not allow number for first character of namespace', () => {
validateNamespace('88MyNamespace', undefined, diagnostics);
expect(diagnostics).toHaveLength(1);
});
it('should enforce namespace being at least 3 characters', () => {
validateNamespace('ab', undefined, diagnostics);
expect(diagnostics).toHaveLength(1);
});
it('should allow $ in the namespace', () => {
const { namespace, fsNamespace } = validateNamespace('$MyNamespace', undefined, diagnostics);
expect(namespace).toBe('$MyNamespace');
expect(fsNamespace).toBe('$mynamespace');
});
it('should allow underscore in the namespace', () => {
const { namespace, fsNamespace } = validateNamespace('My_Namespace', undefined, diagnostics);
expect(namespace).toBe('My_Namespace');
expect(fsNamespace).toBe('my_namespace');
});
it('should allow dash in the namespace', () => {
const { namespace, fsNamespace } = validateNamespace('My-Namespace', undefined, diagnostics);
expect(namespace).toBe('MyNamespace');
expect(fsNamespace).toBe('my-namespace');
});
it('should set user namespace', () => {
const { namespace, fsNamespace } = validateNamespace('MyNamespace', undefined, diagnostics);
expect(namespace).toBe('MyNamespace');
expect(fsNamespace).toBe('mynamespace');
});
it('should set default namespace', () => {
const { namespace, fsNamespace } = validateNamespace(undefined, undefined, diagnostics);
expect(namespace).toBe('App');
expect(fsNamespace).toBe('app');
});
});
================================================
FILE: src/compiler/config/test/validate-output-dist-collection.spec.ts
================================================
import type * as d from '@stencil/core/declarations';
import { mockConfig, mockLoadConfigInit } from '@stencil/core/testing';
import { join, resolve } from '@utils';
import { validateConfig } from '../validate-config';
describe('validateDistCollectionOutputTarget', () => {
let config: d.Config;
const rootDir = resolve('/');
const defaultDir = join(rootDir, 'dist', 'collection');
beforeEach(() => {
config = mockConfig();
});
it('sets correct default values', () => {
const target: d.OutputTargetDistCollection = {
type: 'dist-collection',
empty: false,
dir: null,
collectionDir: null,
};
config.outputTargets = [target];
const { config: validatedConfig } = validateConfig(config, mockLoadConfigInit());
expect(validatedConfig.outputTargets).toEqual([
{
type: 'dist-collection',
empty: false,
dir: defaultDir,
collectionDir: null,
transformAliasedImportPaths: true,
},
]);
});
it('sets specified directory', () => {
const target: d.OutputTargetDistCollection = {
type: 'dist-collection',
empty: false,
dir: '/my-dist',
collectionDir: null,
};
config.outputTargets = [target];
const { config: validatedConfig } = validateConfig(config, mockLoadConfigInit());
expect(validatedConfig.outputTargets).toEqual([
{
type: 'dist-collection',
empty: false,
dir: '/my-dist',
collectionDir: null,
transformAliasedImportPaths: true,
},
]);
});
describe('transformAliasedImportPaths', () => {
it.each([false, true])(
"sets option '%s' when explicitly '%s' in config",
(transformAliasedImportPaths: boolean) => {
const target: d.OutputTargetDistCollection = {
type: 'dist-collection',
empty: false,
dir: null,
collectionDir: null,
transformAliasedImportPaths,
};
config.outputTargets = [target];
const { config: validatedConfig } = validateConfig(config, mockLoadConfigInit());
expect(validatedConfig.outputTargets).toEqual([
{
type: 'dist-collection',
empty: false,
dir: defaultDir,
collectionDir: null,
transformAliasedImportPaths,
},
]);
},
);
});
});
================================================
FILE: src/compiler/config/test/validate-output-dist-custom-element.spec.ts
================================================
import type * as d from '@stencil/core/declarations';
import { mockConfig, mockLoadConfigInit } from '@stencil/core/testing';
import { COPY, DIST_CUSTOM_ELEMENTS, DIST_TYPES, join } from '@utils';
import path from 'path';
import { validateConfig } from '../validate-config';
describe('validate-output-dist-custom-element', () => {
describe('validateCustomElement', () => {
// use Node's resolve() here to simulate a user using either Win/Posix separators (depending on the platform these
// tests are run on)
const rootDir = path.resolve('/');
const defaultDistDir = join(rootDir, 'dist', 'components');
const distCustomElementsDir = 'my-dist-custom-elements';
let userConfig: d.Config;
beforeEach(() => {
userConfig = mockConfig();
});
it('generates a default dist-custom-elements output target', () => {
const outputTarget: d.OutputTargetDistCustomElements = {
type: DIST_CUSTOM_ELEMENTS,
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets).toEqual([
{
type: DIST_TYPES,
dir: defaultDistDir,
typesDir: join(rootDir, 'dist', 'types'),
},
{
type: DIST_CUSTOM_ELEMENTS,
copy: [],
dir: defaultDistDir,
empty: true,
externalRuntime: true,
generateTypeDeclarations: true,
customElementsExportBehavior: 'default',
},
]);
});
it('uses a provided export behavior over the default value', () => {
const outputTarget: d.OutputTargetDistCustomElements = {
type: DIST_CUSTOM_ELEMENTS,
customElementsExportBehavior: 'single-export-module',
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets).toEqual([
{
type: DIST_TYPES,
dir: defaultDistDir,
typesDir: join(rootDir, 'dist', 'types'),
},
{
type: DIST_CUSTOM_ELEMENTS,
copy: [],
dir: defaultDistDir,
empty: true,
externalRuntime: true,
generateTypeDeclarations: true,
customElementsExportBehavior: 'single-export-module',
},
]);
});
it('uses the default export behavior if the specified value is invalid', () => {
const outputTarget: d.OutputTargetDistCustomElements = {
type: DIST_CUSTOM_ELEMENTS,
customElementsExportBehavior: 'not-a-valid-option' as d.CustomElementsExportBehavior,
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets).toEqual([
{
type: DIST_TYPES,
dir: defaultDistDir,
typesDir: join(rootDir, 'dist', 'types'),
},
{
type: DIST_CUSTOM_ELEMENTS,
copy: [],
dir: defaultDistDir,
empty: true,
externalRuntime: true,
generateTypeDeclarations: true,
customElementsExportBehavior: 'default',
},
]);
});
it('uses a provided dir field over a default directory', () => {
const outputTarget: d.OutputTargetDistCustomElements = {
type: DIST_CUSTOM_ELEMENTS,
dir: distCustomElementsDir,
generateTypeDeclarations: false,
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets).toEqual([
{
type: DIST_CUSTOM_ELEMENTS,
copy: [],
dir: join(rootDir, distCustomElementsDir),
empty: true,
externalRuntime: true,
generateTypeDeclarations: false,
customElementsExportBehavior: 'default',
},
]);
});
describe('"empty" field', () => {
it('defaults the "empty" field to true if not provided', () => {
const outputTarget: d.OutputTargetDistCustomElements = {
type: DIST_CUSTOM_ELEMENTS,
externalRuntime: false,
generateTypeDeclarations: false,
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets).toEqual([
{
type: DIST_CUSTOM_ELEMENTS,
copy: [],
dir: defaultDistDir,
empty: true,
externalRuntime: false,
generateTypeDeclarations: false,
customElementsExportBehavior: 'default',
},
]);
});
it('defaults the "empty" field to true it\'s not a boolean', () => {
const outputTarget: d.OutputTargetDistCustomElements = {
type: DIST_CUSTOM_ELEMENTS,
empty: undefined,
externalRuntime: false,
generateTypeDeclarations: false,
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets).toEqual([
{
type: DIST_CUSTOM_ELEMENTS,
copy: [],
dir: defaultDistDir,
empty: true,
externalRuntime: false,
generateTypeDeclarations: false,
customElementsExportBehavior: 'default',
},
]);
});
});
describe('"externalRuntime" field', () => {
it('defaults the "externalRuntime" field to true if not provided', () => {
const outputTarget: d.OutputTargetDistCustomElements = {
type: DIST_CUSTOM_ELEMENTS,
empty: false,
generateTypeDeclarations: false,
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets).toEqual([
{
type: DIST_CUSTOM_ELEMENTS,
copy: [],
dir: defaultDistDir,
empty: false,
externalRuntime: true,
generateTypeDeclarations: false,
customElementsExportBehavior: 'default',
},
]);
});
it('defaults the "externalRuntime" field to true it\'s not a boolean', () => {
const outputTarget: d.OutputTargetDistCustomElements = {
type: DIST_CUSTOM_ELEMENTS,
empty: false,
externalRuntime: undefined,
generateTypeDeclarations: false,
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets).toEqual([
{
type: DIST_CUSTOM_ELEMENTS,
copy: [],
dir: defaultDistDir,
empty: false,
externalRuntime: true,
generateTypeDeclarations: false,
customElementsExportBehavior: 'default',
},
]);
});
});
describe('"generateTypeDeclarations" field', () => {
it('defaults the "generateTypeDeclarations" field to true if not provided', () => {
const outputTarget: d.OutputTargetDistCustomElements = {
type: DIST_CUSTOM_ELEMENTS,
empty: false,
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets).toEqual([
{
type: DIST_TYPES,
dir: defaultDistDir,
typesDir: join(rootDir, 'dist', 'types'),
},
{
type: DIST_CUSTOM_ELEMENTS,
copy: [],
dir: defaultDistDir,
empty: false,
externalRuntime: true,
generateTypeDeclarations: true,
customElementsExportBehavior: 'default',
},
]);
});
it('defaults the "generateTypeDeclarations" field to true it\'s not a boolean', () => {
const outputTarget: d.OutputTargetDistCustomElements = {
type: DIST_CUSTOM_ELEMENTS,
empty: false,
generateTypeDeclarations: undefined,
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets).toEqual([
{
type: DIST_TYPES,
dir: defaultDistDir,
typesDir: join(rootDir, 'dist', 'types'),
},
{
type: DIST_CUSTOM_ELEMENTS,
copy: [],
dir: defaultDistDir,
empty: false,
externalRuntime: true,
generateTypeDeclarations: true,
customElementsExportBehavior: 'default',
},
]);
});
it('creates a types directory when "generateTypeDeclarations" is true', () => {
const outputTarget: d.OutputTargetDistCustomElements = {
type: DIST_CUSTOM_ELEMENTS,
empty: false,
externalRuntime: false,
generateTypeDeclarations: true,
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets).toEqual([
{
type: DIST_TYPES,
dir: defaultDistDir,
typesDir: join(rootDir, 'dist', 'types'),
},
{
type: DIST_CUSTOM_ELEMENTS,
copy: [],
dir: defaultDistDir,
empty: false,
externalRuntime: false,
generateTypeDeclarations: true,
customElementsExportBehavior: 'default',
},
]);
});
it('creates a types directory for a custom directory', () => {
const outputTarget: d.OutputTargetDistCustomElements = {
type: DIST_CUSTOM_ELEMENTS,
dir: distCustomElementsDir,
empty: false,
externalRuntime: false,
generateTypeDeclarations: true,
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets).toEqual([
{
type: DIST_TYPES,
dir: join(rootDir, distCustomElementsDir),
typesDir: join(rootDir, 'dist', 'types'),
},
{
type: DIST_CUSTOM_ELEMENTS,
copy: [],
dir: join(rootDir, distCustomElementsDir),
empty: false,
externalRuntime: false,
generateTypeDeclarations: true,
customElementsExportBehavior: 'default',
},
]);
});
it('doesn\'t create a types directory when "generateTypeDeclarations" is false', () => {
const outputTarget: d.OutputTargetDistCustomElements = {
type: DIST_CUSTOM_ELEMENTS,
empty: false,
externalRuntime: false,
generateTypeDeclarations: false,
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets).toEqual([
{
type: DIST_CUSTOM_ELEMENTS,
copy: [],
dir: defaultDistDir,
empty: false,
externalRuntime: false,
generateTypeDeclarations: false,
customElementsExportBehavior: 'default',
},
]);
});
});
describe('copy tasks', () => {
it('copies existing copy tasks over to the output target', () => {
const copyOutputTarget: d.CopyTask = {
src: 'mock/src',
dest: 'mock/dest',
};
const copyOutputTarget2: d.CopyTask = {
src: 'mock/src2',
dest: 'mock/dest2',
};
const outputTarget: d.OutputTargetDistCustomElements = {
type: DIST_CUSTOM_ELEMENTS,
copy: [copyOutputTarget, copyOutputTarget2],
dir: distCustomElementsDir,
empty: false,
externalRuntime: false,
generateTypeDeclarations: false,
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets).toEqual([
{
type: COPY,
dir: rootDir,
copy: [copyOutputTarget, copyOutputTarget2],
},
{
type: DIST_CUSTOM_ELEMENTS,
copy: [copyOutputTarget, copyOutputTarget2],
dir: join(rootDir, distCustomElementsDir),
empty: false,
externalRuntime: false,
generateTypeDeclarations: false,
customElementsExportBehavior: 'default',
},
]);
});
});
describe('"autoLoader" field', () => {
it('normalizes autoLoader: true to an object with defaults', () => {
const outputTarget: d.OutputTargetDistCustomElements = {
type: DIST_CUSTOM_ELEMENTS,
autoLoader: true,
generateTypeDeclarations: false,
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
const distCustomElementsTarget = config.outputTargets.find(
(o) => o.type === DIST_CUSTOM_ELEMENTS,
) as d.OutputTargetDistCustomElements;
expect(distCustomElementsTarget.autoLoader).toEqual({
fileName: 'loader',
autoStart: true,
});
});
it('normalizes autoLoader object with partial options', () => {
const outputTarget: d.OutputTargetDistCustomElements = {
type: DIST_CUSTOM_ELEMENTS,
autoLoader: { fileName: 'my-loader' },
generateTypeDeclarations: false,
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
const distCustomElementsTarget = config.outputTargets.find(
(o) => o.type === DIST_CUSTOM_ELEMENTS,
) as d.OutputTargetDistCustomElements;
expect(distCustomElementsTarget.autoLoader).toEqual({
fileName: 'my-loader',
autoStart: true,
});
});
it('normalizes autoLoader object with autoStart: false', () => {
const outputTarget: d.OutputTargetDistCustomElements = {
type: DIST_CUSTOM_ELEMENTS,
autoLoader: { autoStart: false },
generateTypeDeclarations: false,
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
const distCustomElementsTarget = config.outputTargets.find(
(o) => o.type === DIST_CUSTOM_ELEMENTS,
) as d.OutputTargetDistCustomElements;
expect(distCustomElementsTarget.autoLoader).toEqual({
fileName: 'loader',
autoStart: false,
});
});
it('does not set autoLoader when not provided', () => {
const outputTarget: d.OutputTargetDistCustomElements = {
type: DIST_CUSTOM_ELEMENTS,
generateTypeDeclarations: false,
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
const distCustomElementsTarget = config.outputTargets.find(
(o) => o.type === DIST_CUSTOM_ELEMENTS,
) as d.OutputTargetDistCustomElements;
expect(distCustomElementsTarget.autoLoader).toBeUndefined();
});
it('does not set autoLoader when explicitly false', () => {
const outputTarget: d.OutputTargetDistCustomElements = {
type: DIST_CUSTOM_ELEMENTS,
autoLoader: false,
generateTypeDeclarations: false,
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
const distCustomElementsTarget = config.outputTargets.find(
(o) => o.type === DIST_CUSTOM_ELEMENTS,
) as d.OutputTargetDistCustomElements;
expect(distCustomElementsTarget.autoLoader).toBe(false);
});
});
});
});
================================================
FILE: src/compiler/config/test/validate-output-dist.spec.ts
================================================
import type * as d from '@stencil/core/declarations';
import { mockConfig, mockLoadConfigInit } from '@stencil/core/testing';
import { join } from '@utils';
import path from 'path';
import { validateConfig } from '../validate-config';
describe('validateDistOutputTarget', () => {
// use Node's resolve() here to simulate a user using either Win/Posix separators (depending on the platform these
// tests are run on)
const rootDir = path.resolve('/');
let userConfig: d.Config;
beforeEach(() => {
userConfig = mockConfig({ fsNamespace: 'testing' });
});
it('should set dist values', () => {
const outputTarget: d.OutputTargetDist = {
type: 'dist',
dir: 'my-dist',
buildDir: 'my-build',
empty: false,
};
userConfig.outputTargets = [outputTarget];
userConfig.buildDist = true;
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets).toEqual([
{
buildDir: join(rootDir, 'my-dist', 'my-build'),
collectionDir: join(rootDir, 'my-dist', 'collection'),
copy: [],
dir: join(rootDir, 'my-dist'),
empty: false,
esmLoaderPath: join(rootDir, 'my-dist', 'loader'),
type: 'dist',
polyfills: false,
typesDir: join(rootDir, 'my-dist', 'types'),
transformAliasedImportPathsInCollection: true,
isPrimaryPackageOutputTarget: false,
},
{
esmDir: join(rootDir, 'my-dist', 'my-build', 'testing'),
empty: false,
isBrowserBuild: true,
legacyLoaderFile: join(rootDir, 'my-dist', 'my-build', 'testing.js'),
polyfills: true,
systemDir: undefined,
systemLoaderFile: undefined,
type: 'dist-lazy',
},
{
copyAssets: 'dist',
copy: [],
dir: join(rootDir, 'my-dist', 'my-build', 'testing'),
type: 'copy',
},
{
file: join(rootDir, 'my-dist', 'my-build', 'testing', 'testing.css'),
type: 'dist-global-styles',
},
{
dir: join(rootDir, 'my-dist'),
type: 'dist-types',
typesDir: join(rootDir, 'my-dist', 'types'),
},
{
collectionDir: join(rootDir, 'my-dist', 'collection'),
dir: join(rootDir, '/my-dist'),
empty: false,
transformAliasedImportPaths: true,
type: 'dist-collection',
},
{
copy: [{ src: '**/*.svg' }, { src: '**/*.js' }],
copyAssets: 'collection',
dir: join(rootDir, 'my-dist', 'collection'),
type: 'copy',
},
{
type: 'dist-lazy',
cjsDir: join(rootDir, 'my-dist', 'cjs'),
cjsIndexFile: join(rootDir, 'my-dist', 'index.cjs.js'),
empty: false,
esmDir: join(rootDir, 'my-dist', 'esm'),
esmEs5Dir: undefined,
esmIndexFile: join(rootDir, 'my-dist', 'index.js'),
polyfills: true,
},
{
cjsDir: join(rootDir, 'my-dist', 'cjs'),
componentDts: join(rootDir, 'my-dist', 'types', 'components.d.ts'),
dir: join(rootDir, 'my-dist', 'loader'),
empty: false,
esmDir: join(rootDir, 'my-dist', 'esm'),
esmEs5Dir: undefined,
type: 'dist-lazy-loader',
},
]);
});
it('should set defaults when outputTargets dist is empty', () => {
userConfig.outputTargets = [{ type: 'dist' }];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
const outputTarget = config.outputTargets.find((o) => o.type === 'dist') as d.OutputTargetDist;
expect(outputTarget).toBeDefined();
expect(outputTarget.dir).toBe(join(rootDir, 'dist'));
expect(outputTarget.buildDir).toBe(join(rootDir, '/dist'));
expect(outputTarget.empty).toBe(true);
});
it('should default to not add dist when outputTargets exists, but without dist', () => {
userConfig.outputTargets = [];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets.some((o) => o.type === 'dist')).toBe(false);
});
it('sets option to transform aliased import paths when enabled', () => {
const outputTarget: d.OutputTargetDist = {
type: 'dist',
dir: 'my-dist',
buildDir: 'my-build',
empty: false,
transformAliasedImportPathsInCollection: true,
};
userConfig.outputTargets = [outputTarget];
userConfig.buildDist = true;
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets).toEqual([
{
buildDir: join(rootDir, 'my-dist', 'my-build'),
collectionDir: join(rootDir, 'my-dist', 'collection'),
copy: [],
dir: join(rootDir, 'my-dist'),
empty: false,
esmLoaderPath: join(rootDir, 'my-dist', 'loader'),
type: 'dist',
polyfills: false,
typesDir: join(rootDir, 'my-dist', 'types'),
transformAliasedImportPathsInCollection: true,
isPrimaryPackageOutputTarget: false,
},
{
esmDir: join(rootDir, 'my-dist', 'my-build', 'testing'),
empty: false,
isBrowserBuild: true,
legacyLoaderFile: join(rootDir, 'my-dist', 'my-build', 'testing.js'),
polyfills: true,
systemDir: undefined,
systemLoaderFile: undefined,
type: 'dist-lazy',
},
{
copyAssets: 'dist',
copy: [],
dir: join(rootDir, 'my-dist', 'my-build', 'testing'),
type: 'copy',
},
{
file: join(rootDir, 'my-dist', 'my-build', 'testing', 'testing.css'),
type: 'dist-global-styles',
},
{
dir: join(rootDir, 'my-dist'),
type: 'dist-types',
typesDir: join(rootDir, 'my-dist', 'types'),
},
{
collectionDir: join(rootDir, 'my-dist', 'collection'),
dir: join(rootDir, '/my-dist'),
empty: false,
transformAliasedImportPaths: true,
type: 'dist-collection',
},
{
copy: [{ src: '**/*.svg' }, { src: '**/*.js' }],
copyAssets: 'collection',
dir: join(rootDir, 'my-dist', 'collection'),
type: 'copy',
},
{
type: 'dist-lazy',
cjsDir: join(rootDir, 'my-dist', 'cjs'),
cjsIndexFile: join(rootDir, 'my-dist', 'index.cjs.js'),
empty: false,
esmDir: join(rootDir, 'my-dist', 'esm'),
esmEs5Dir: undefined,
esmIndexFile: join(rootDir, 'my-dist', 'index.js'),
polyfills: true,
},
{
cjsDir: join(rootDir, 'my-dist', 'cjs'),
componentDts: join(rootDir, 'my-dist', 'types', 'components.d.ts'),
dir: join(rootDir, 'my-dist', 'loader'),
empty: false,
esmDir: join(rootDir, 'my-dist', 'esm'),
esmEs5Dir: undefined,
type: 'dist-lazy-loader',
},
]);
});
it('sets option to validate primary package output target when enabled', () => {
const outputTarget: d.OutputTargetDist = {
type: 'dist',
dir: 'my-dist',
buildDir: 'my-build',
empty: false,
isPrimaryPackageOutputTarget: true,
};
userConfig.outputTargets = [outputTarget];
userConfig.buildDist = true;
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets).toEqual([
{
buildDir: join(rootDir, 'my-dist', 'my-build'),
collectionDir: join(rootDir, 'my-dist', 'collection'),
copy: [],
dir: join(rootDir, 'my-dist'),
empty: false,
esmLoaderPath: join(rootDir, 'my-dist', 'loader'),
type: 'dist',
polyfills: false,
typesDir: join(rootDir, 'my-dist', 'types'),
transformAliasedImportPathsInCollection: true,
isPrimaryPackageOutputTarget: true,
},
{
esmDir: join(rootDir, 'my-dist', 'my-build', 'testing'),
empty: false,
isBrowserBuild: true,
legacyLoaderFile: join(rootDir, 'my-dist', 'my-build', 'testing.js'),
polyfills: true,
systemDir: undefined,
systemLoaderFile: undefined,
type: 'dist-lazy',
},
{
copyAssets: 'dist',
copy: [],
dir: join(rootDir, 'my-dist', 'my-build', 'testing'),
type: 'copy',
},
{
file: join(rootDir, 'my-dist', 'my-build', 'testing', 'testing.css'),
type: 'dist-global-styles',
},
{
dir: join(rootDir, 'my-dist'),
type: 'dist-types',
typesDir: join(rootDir, 'my-dist', 'types'),
},
{
collectionDir: join(rootDir, 'my-dist', 'collection'),
dir: join(rootDir, '/my-dist'),
empty: false,
transformAliasedImportPaths: true,
type: 'dist-collection',
},
{
copy: [{ src: '**/*.svg' }, { src: '**/*.js' }],
copyAssets: 'collection',
dir: join(rootDir, 'my-dist', 'collection'),
type: 'copy',
},
{
type: 'dist-lazy',
cjsDir: join(rootDir, 'my-dist', 'cjs'),
cjsIndexFile: join(rootDir, 'my-dist', 'index.cjs.js'),
empty: false,
esmDir: join(rootDir, 'my-dist', 'esm'),
esmEs5Dir: undefined,
esmIndexFile: join(rootDir, 'my-dist', 'index.js'),
polyfills: true,
},
{
cjsDir: join(rootDir, 'my-dist', 'cjs'),
componentDts: join(rootDir, 'my-dist', 'types', 'components.d.ts'),
dir: join(rootDir, 'my-dist', 'loader'),
empty: false,
esmDir: join(rootDir, 'my-dist', 'esm'),
esmEs5Dir: undefined,
type: 'dist-lazy-loader',
},
]);
});
});
================================================
FILE: src/compiler/config/test/validate-output-www.spec.ts
================================================
import type * as d from '@stencil/core/declarations';
import { mockLoadConfigInit } from '@stencil/core/testing';
import { isOutputTargetCopy, isOutputTargetHydrate, isOutputTargetWww, join } from '@utils';
import path from 'path';
import { ConfigFlags, createConfigFlags } from '../../../cli/config-flags';
import { validateConfig } from '../validate-config';
describe('validateOutputTargetWww', () => {
// use Node's resolve() here to simulate a user using either Win/Posix separators (depending on the platform these
// tests are run on)
const rootDir = path.resolve('/');
let userConfig: d.Config;
let flags: ConfigFlags;
beforeEach(() => {
flags = createConfigFlags();
userConfig = {
rootDir: rootDir,
flags,
};
});
it('should have default value', () => {
const outputTarget: d.OutputTargetWww = {
type: 'www',
// use Node's join() here to simulate a user using either Win/Posix separators (depending on the platform these
// tests are run on) for their input
dir: path.join('www', 'docs'),
};
userConfig.outputTargets = [outputTarget];
userConfig.buildEs5 = false;
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets).toEqual([
{
appDir: join(rootDir, 'www', 'docs'),
baseUrl: '/',
buildDir: join(rootDir, 'www', 'docs', 'build'),
dir: join(rootDir, 'www', 'docs'),
empty: true,
indexHtml: join(rootDir, 'www', 'docs', 'index.html'),
polyfills: true,
serviceWorker: {
dontCacheBustURLsMatching: /p-\w{8}/,
globDirectory: join(rootDir, 'www', 'docs'),
globIgnores: [
'**/host.config.json',
'**/*.system.entry.js',
'**/*.system.js',
'**/app.js',
'**/app.esm.js',
'**/app.css',
],
globPatterns: ['*.html', '**/*.{js,css,json}'],
swDest: join(rootDir, 'www', 'docs', 'sw.js'),
},
type: 'www',
},
{
dir: join(rootDir, 'www', 'docs', 'build'),
esmDir: join(rootDir, 'www', 'docs', 'build'),
isBrowserBuild: true,
polyfills: true,
systemDir: undefined,
systemLoaderFile: undefined,
type: 'dist-lazy',
},
{
copyAssets: 'dist',
dir: join(rootDir, 'www', 'docs', 'build'),
type: 'copy',
},
{
copy: [
{
src: 'assets',
warn: false,
},
{
src: 'manifest.json',
warn: false,
},
],
dir: join(rootDir, 'www', 'docs'),
type: 'copy',
},
{
file: join(rootDir, 'www', 'docs', 'build', 'app.css'),
type: 'dist-global-styles',
},
]);
});
it('should www with sub directory', () => {
const outputTarget: d.OutputTargetWww = {
type: 'www',
// use Node's join() here to simulate a user using either Win/Posix separators (depending on the platform these
// tests are run on) for their input
dir: path.join('www', 'docs'),
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
const www = config.outputTargets.find(isOutputTargetWww) as d.OutputTargetWww;
expect(www.dir).toBe(join(rootDir, 'www', 'docs'));
expect(www.appDir).toBe(join(rootDir, 'www', 'docs'));
expect(www.buildDir).toBe(join(rootDir, 'www', 'docs', 'build'));
expect(www.indexHtml).toBe(join(rootDir, 'www', 'docs', 'index.html'));
});
it('should set www values', () => {
const outputTarget: d.OutputTargetWww = {
type: 'www',
dir: 'my-www',
buildDir: 'my-build',
indexHtml: 'my-index.htm',
empty: false,
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
const www = config.outputTargets.find(isOutputTargetWww) as d.OutputTargetWww;
expect(www.type).toBe('www');
expect(www.dir).toBe(join(rootDir, 'my-www'));
expect(www.buildDir).toBe(join(rootDir, 'my-www', 'my-build'));
expect(www.indexHtml).toBe(join(rootDir, 'my-www', 'my-index.htm'));
expect(www.empty).toBe(false);
});
it('should default to add www when outputTargets is undefined', () => {
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets).toHaveLength(5);
const outputTarget = config.outputTargets.find(isOutputTargetWww) as d.OutputTargetWww;
expect(outputTarget.dir).toBe(join(rootDir, 'www'));
expect(outputTarget.buildDir).toBe(join(rootDir, 'www', 'build'));
expect(outputTarget.indexHtml).toBe(join(rootDir, 'www', 'index.html'));
expect(outputTarget.empty).toBe(true);
});
describe('baseUrl', () => {
it('baseUrl does not end with / with dir set', () => {
const outputTarget: d.OutputTargetWww = {
type: 'www',
dir: 'my-www',
baseUrl: '/docs',
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
const www = config.outputTargets.find(isOutputTargetWww) as d.OutputTargetWww;
expect(www.type).toBe('www');
expect(www.dir).toBe(join(rootDir, 'my-www'));
expect(www.baseUrl).toBe('/docs/');
expect(www.appDir).toBe(join(rootDir, 'my-www/docs'));
expect(www.buildDir).toBe(join(rootDir, 'my-www', 'docs', 'build'));
expect(www.indexHtml).toBe(join(rootDir, 'my-www', 'docs', 'index.html'));
});
it('baseUrl does not end with /', () => {
const outputTarget: d.OutputTargetWww = {
type: 'www',
baseUrl: '/docs',
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
const www = config.outputTargets.find(isOutputTargetWww) as d.OutputTargetWww;
expect(www.type).toBe('www');
expect(www.dir).toBe(join(rootDir, 'www'));
expect(www.baseUrl).toBe('/docs/');
expect(www.appDir).toBe(join(rootDir, 'www/docs'));
expect(www.buildDir).toBe(join(rootDir, 'www', 'docs', 'build'));
expect(www.indexHtml).toBe(join(rootDir, 'www', 'docs', 'index.html'));
});
it('baseUrl is a full url', () => {
const outputTarget: d.OutputTargetWww = {
type: 'www',
baseUrl: 'https://example.com/docs',
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
const www = config.outputTargets.find(isOutputTargetWww) as d.OutputTargetWww;
expect(www.type).toBe('www');
expect(www.dir).toBe(join(rootDir, 'www'));
expect(www.baseUrl).toBe('https://example.com/docs/');
expect(www.appDir).toBe(join(rootDir, 'www/docs'));
expect(www.buildDir).toBe(join(rootDir, 'www', 'docs', 'build'));
expect(www.indexHtml).toBe(join(rootDir, 'www', 'docs', 'index.html'));
});
});
describe('copy', () => {
it('should add copy tasks', () => {
const outputTarget: d.OutputTargetWww = {
type: 'www',
// use Node's join() here to simulate a user using either Win/Posix separators (depending on the platform these
// tests are run on) for their input
dir: path.join('www', 'docs'),
copy: [
{
src: 'index-modules.html',
dest: 'index-2.html',
},
],
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
const copyTargets = config.outputTargets.filter(isOutputTargetCopy);
expect(copyTargets).toEqual([
{
copyAssets: 'dist',
dir: join(rootDir, 'www', 'docs', 'build'),
type: 'copy',
},
{
copy: [
{
dest: 'index-2.html',
src: 'index-modules.html',
},
{
src: 'assets',
warn: false,
},
{
src: 'manifest.json',
warn: false,
},
],
dir: join(rootDir, 'www', 'docs'),
type: 'copy',
},
]);
});
it('should replace copy tasks', () => {
const outputTarget: d.OutputTargetWww = {
type: 'www',
// use Node's join() here to simulate a user using either Win/Posix separators (depending on the platform these
// tests are run on) for their input
dir: path.join('www', 'docs'),
copy: [
{
src: 'assets',
dest: 'assets2',
},
],
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
const copyTargets = config.outputTargets.filter(isOutputTargetCopy);
expect(copyTargets).toEqual([
{
copyAssets: 'dist',
dir: join(rootDir, 'www', 'docs', 'build'),
type: 'copy',
},
{
copy: [
{
dest: 'assets2',
src: 'assets',
},
{
src: 'manifest.json',
warn: false,
},
],
dir: join(rootDir, 'www', 'docs'),
type: 'copy',
},
]);
});
it('should disable copy tasks', () => {
const outputTarget: d.OutputTargetWww = {
type: 'www',
// use Node's join() here to simulate a user using either Win/Posix separators (depending on the platform these
// tests are run on) for their input
dir: path.join('www', 'docs'),
copy: null,
};
userConfig.outputTargets = [outputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
const copyTargets = config.outputTargets.filter(isOutputTargetCopy);
expect(copyTargets).toEqual([
{
copyAssets: 'dist',
dir: join(rootDir, 'www', 'docs', 'build'),
type: 'copy',
},
{
copy: [],
dir: join(rootDir, 'www', 'docs'),
type: 'copy',
},
]);
});
});
describe('dist-hydrate-script', () => {
it('should not add hydrate by default', () => {
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets.some((o) => o.type === 'dist-hydrate-script')).toBe(false);
expect(config.outputTargets.some((o) => o.type === 'www')).toBe(true);
});
it('should not add hydrate with user www', () => {
const wwwOutputTarget: d.OutputTargetWww = {
type: 'www',
};
userConfig.outputTargets = [wwwOutputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets.some((o) => o.type === 'dist-hydrate-script')).toBe(false);
expect(config.outputTargets.some((o) => o.type === 'www')).toBe(true);
});
it('should add hydrate with user hydrate and www outputs', () => {
const wwwOutputTarget: d.OutputTargetWww = {
type: 'www',
};
const hydrateOutputTarget: d.OutputTargetHydrate = {
type: 'dist-hydrate-script',
};
userConfig.outputTargets = [wwwOutputTarget, hydrateOutputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets.some((o) => o.type === 'dist-hydrate-script')).toBe(true);
expect(config.outputTargets.some((o) => o.type === 'www')).toBe(true);
});
it('should add hydrate with --prerender flag', () => {
userConfig.flags = { ...flags, prerender: true };
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets.some((o) => o.type === 'dist-hydrate-script')).toBe(true);
expect(config.outputTargets.some((o) => o.type === 'www')).toBe(true);
});
it('should add hydrate with --ssr flag', () => {
userConfig.flags = { ...flags, ssr: true };
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets.some((o) => o.type === 'dist-hydrate-script')).toBe(true);
expect(config.outputTargets.some((o) => o.type === 'www')).toBe(true);
});
it('should add externals and defaults', () => {
const hydrateOutputTarget: d.OutputTargetHydrate = {
type: 'dist-hydrate-script',
external: ['lodash', 'left-pad'],
};
userConfig.outputTargets = [hydrateOutputTarget];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
const o = config.outputTargets.find(isOutputTargetHydrate) as d.OutputTargetHydrate;
expect(o.external).toContain('lodash');
expect(o.external).toContain('left-pad');
expect(o.external).toContain('fs');
expect(o.external).toContain('path');
expect(o.external).toContain('crypto');
});
it('should add node builtins to external by default', () => {
userConfig.flags = { ...flags, prerender: true };
const { config } = validateConfig(userConfig, mockLoadConfigInit());
const o = config.outputTargets.find(isOutputTargetHydrate) as d.OutputTargetHydrate;
expect(o.external).toContain('fs');
expect(o.external).toContain('path');
expect(o.external).toContain('crypto');
});
});
});
================================================
FILE: src/compiler/config/test/validate-paths.spec.ts
================================================
import type * as d from '@stencil/core/declarations';
import { mockCompilerSystem, mockLoadConfigInit, mockLogger } from '@stencil/core/testing';
import { join } from '@utils';
import path from 'path';
import { validateConfig } from '../validate-config';
describe('validatePaths', () => {
let userConfig: d.Config;
const logger = mockLogger();
const sys = mockCompilerSystem();
// use Node's resolve() here to simulate a user using either Win/Posix separators (depending on the platform these
// tests are run on)
const ROOT = path.resolve('/');
beforeEach(() => {
userConfig = {
sys: sys as any,
logger: logger,
// use Node's join() here to simulate a user using either Win/Posix separators (depending on the platform these
// tests are run on) for their input
rootDir: path.join(ROOT, 'User', 'my-app'),
namespace: 'Testing',
};
});
it('should set absolute cacheDir', () => {
// use Node's join() here to simulate a user using either Win/Posix separators (depending on the platform these
// tests are run on) for their input
userConfig.cacheDir = path.join(ROOT, 'some', 'custom', 'cache');
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.cacheDir).toBe(join(ROOT, 'some', 'custom', 'cache'));
});
it('should set relative cacheDir', () => {
userConfig.cacheDir = 'custom-cache';
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.cacheDir).toBe(join(ROOT, 'User', 'my-app', 'custom-cache'));
});
it('should set default cacheDir', () => {
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.cacheDir).toBe(join(ROOT, 'User', 'my-app', '.stencil'));
});
it('should set default wwwIndexHtml and convert to absolute path', () => {
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(path.basename((config.outputTargets as d.OutputTargetWww[])[0].indexHtml!)).toBe('index.html');
expect(path.isAbsolute((config.outputTargets as d.OutputTargetWww[])[0].indexHtml!)).toBe(true);
});
it('should convert a custom wwwIndexHtml to absolute path', () => {
userConfig.outputTargets = [
{
type: 'www',
// use Node's join() here to simulate a user using either Win/Posix separators (depending on the platform these
// tests are run on) for their input
indexHtml: path.join('assets', 'custom-index.html'),
},
] as d.OutputTargetWww[];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(path.basename((config.outputTargets as d.OutputTargetWww[])[0].indexHtml!)).toBe('custom-index.html');
expect(path.isAbsolute((config.outputTargets as d.OutputTargetWww[])[0].indexHtml!)).toBe(true);
});
it('should set default indexHtmlSrc and convert to absolute path', () => {
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(path.basename(config.srcIndexHtml)).toBe('index.html');
expect(path.isAbsolute(config.srcIndexHtml)).toBe(true);
});
it('should set emptyDist to false', () => {
userConfig.outputTargets = [
{
type: 'www',
empty: false,
},
] as d.OutputTargetWww[];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect((config.outputTargets as d.OutputTargetWww[])[0].empty).toBe(false);
});
it('should set default emptyWWW to true', () => {
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect((config.outputTargets as d.OutputTargetWww[])[0].empty).toBe(true);
});
it('should set emptyWWW to false', () => {
userConfig.outputTargets = [
{
type: 'www',
empty: false,
},
] as d.OutputTargetWww[];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect((config.outputTargets as d.OutputTargetWww[])[0].empty).toBe(false);
});
it('should set default collection dir and convert to absolute path', () => {
userConfig.outputTargets = [
{
type: 'dist',
},
];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(path.basename((config.outputTargets as d.OutputTargetDist[])[0].collectionDir!)).toBe('collection');
expect(path.isAbsolute((config.outputTargets as d.OutputTargetDist[])[0].collectionDir!)).toBe(true);
});
it('should set default types dir and convert to absolute path', () => {
userConfig.outputTargets = [
{
type: 'dist',
},
];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(path.basename((config.outputTargets as d.OutputTargetDist[])[0].typesDir!)).toBe('types');
expect(path.isAbsolute((config.outputTargets as d.OutputTargetDist[])[0].typesDir!)).toBe(true);
});
it('should set default build dir and convert to absolute path', () => {
const { config } = validateConfig(userConfig, mockLoadConfigInit());
// the path will be normalized by Stencil us use '/', split on that regardless of platform
const parts = (config.outputTargets as d.OutputTargetDist[])[0].buildDir!.split('/');
expect(parts[parts.length - 1]).toBe('build');
expect(parts[parts.length - 2]).toBe('www');
expect(path.isAbsolute((config.outputTargets as d.OutputTargetDist[])[0].buildDir!)).toBe(true);
});
it('should set build dir w/ custom www', () => {
userConfig.outputTargets = [
{
type: 'www',
dir: 'custom-www',
},
] as d.OutputTargetWww[];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
// the path will be normalized by Stencil us use '/', split on that regardless of platform
const parts = (config.outputTargets as d.OutputTargetDist[])[0].buildDir!.split('/');
expect(parts[parts.length - 1]).toBe('build');
expect(parts[parts.length - 2]).toBe('custom-www');
expect(path.isAbsolute((config.outputTargets as d.OutputTargetDist[])[0].buildDir!)).toBe(true);
});
it('should set default src dir and convert to absolute path', () => {
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(path.basename(config.srcDir)).toBe('src');
expect(path.isAbsolute(config.srcDir)).toBe(true);
});
it('should set src dir and convert to absolute path', () => {
userConfig.srcDir = 'app';
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(path.basename(config.srcDir)).toBe('app');
expect(path.isAbsolute(config.srcDir)).toBe(true);
});
it('should convert globalScript to absolute path, if a globalScript property was provided', () => {
// use Node's join() here to simulate a user using either Win/Posix separators (depending on the platform these
// tests are run on) for their input
userConfig.globalScript = path.join('src', 'global', 'index.ts');
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(path.basename(config.globalScript!)).toBe('index.ts');
expect(path.isAbsolute(config.globalScript!)).toBe(true);
});
it('should convert globalStyle string to absolute path array, if a globalStyle property was provided', () => {
// use Node's join() here to simulate a user using either Win/Posix separators (depending on the platform these
// tests are run on) for their input
userConfig.globalStyle = path.join('src', 'global', 'styles.css');
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(path.basename(config.globalStyle!)).toBe('styles.css');
expect(path.isAbsolute(config.globalStyle!)).toBe(true);
});
});
================================================
FILE: src/compiler/config/test/validate-rollup-config.spec.ts
================================================
import type * as d from '@stencil/core/declarations';
import { validateRollupConfig } from '../validate-rollup-config';
describe('validateStats', () => {
let config: d.Config;
beforeEach(() => {
config = {};
});
it('should use default if no config provided', () => {
const rollupConfig = validateRollupConfig(config);
expect(rollupConfig).toEqual({
inputOptions: {},
outputOptions: {},
});
});
it('should set based on inputOptions if provided', () => {
config.rollupConfig = {
inputOptions: {
context: 'window',
},
};
const rollupConfig = validateRollupConfig(config);
expect(rollupConfig).toEqual({
inputOptions: {
context: 'window',
},
outputOptions: {},
});
});
it('should use default if inputOptions is not provided but outputOptions is', () => {
config.rollupConfig = {
outputOptions: {
globals: {
jquery: '$',
},
},
};
const rollupConfig = validateRollupConfig(config);
expect(rollupConfig).toEqual({
inputOptions: {},
outputOptions: {
globals: {
jquery: '$',
},
},
});
});
it('should pass all valid config data through and not those that are extraneous', () => {
config.rollupConfig = {
inputOptions: {
context: 'window',
external: 'external_symbol',
notAnOption: {},
},
outputOptions: {
globals: {
jquery: '$',
},
},
} as d.RollupConfig;
const rollupConfig = validateRollupConfig(config);
expect(rollupConfig).toEqual({
inputOptions: {
context: 'window',
external: 'external_symbol',
},
outputOptions: {
globals: {
jquery: '$',
},
},
});
});
});
================================================
FILE: src/compiler/config/test/validate-service-worker.spec.ts
================================================
import type * as d from '@stencil/core/declarations';
import { OutputTargetWww } from '@stencil/core/declarations';
import { mockCompilerSystem, mockLogger, mockValidatedConfig } from '@stencil/core/testing';
import { createConfigFlags } from '../../../cli/config-flags';
import { validateServiceWorker } from '../validate-service-worker';
describe('validateServiceWorker', () => {
let config: d.ValidatedConfig;
let outputTarget: d.OutputTargetWww;
beforeEach(() => {
config = mockValidatedConfig({
devMode: false,
flags: createConfigFlags(),
fsNamespace: 'app',
hydratedFlag: null,
logger: mockLogger(),
outputTargets: [],
packageJsonFilePath: '/package.json',
rootDir: '/',
sys: mockCompilerSystem(),
testing: {},
transformAliasedImportPaths: true,
});
});
/**
* A little util to work around a typescript annoyance. Because
* `outputTarget.serviceWorker` is typed as
* `serviceWorker?: ServiceWorkerConfig | null | false;` we get type errors
* all over if we try to just access it directly. So instead, do a little
* check to see if it's falsy. If not, we return it, and if it is we fail the test.
*
* @param target the output target from which we want to pull the serviceWorker
* @returns a serviceWorker object or `void`, with a `void` return being
* accompanied by a manually-triggered test failure.
*/
function getServiceWorker(target: OutputTargetWww) {
if (target.serviceWorker) {
return target.serviceWorker;
} else {
throw new Error('the serviceWorker on the provided target was unexpectedly falsy, so this test needs to fail!');
}
}
it('should add host.config.json to globIgnores', () => {
outputTarget = {
type: 'www',
appDir: '/User/me/app/www/',
};
validateServiceWorker(config, outputTarget);
expect(getServiceWorker(outputTarget).globIgnores).toContain('**/host.config.json');
});
it('should set globIgnores from string', () => {
outputTarget = {
type: 'www',
appDir: '/User/me/app/www/',
serviceWorker: {
globIgnores: '**/some-file.js',
},
};
validateServiceWorker(config, outputTarget);
expect(getServiceWorker(outputTarget).globIgnores).toContain('**/some-file.js');
});
it('should set globDirectory', () => {
outputTarget = {
type: 'www',
appDir: '/User/me/app/www/',
serviceWorker: {
globDirectory: '/custom/www',
},
};
validateServiceWorker(config, outputTarget);
expect(getServiceWorker(outputTarget).globDirectory).toBe('/custom/www');
});
it('should set default globDirectory', () => {
outputTarget = {
type: 'www',
appDir: '/User/me/app/www/',
};
validateServiceWorker(config, outputTarget);
expect(getServiceWorker(outputTarget).globDirectory).toBe('/User/me/app/www/');
});
it('should set globPatterns array', () => {
outputTarget = {
type: 'www',
appDir: '/www',
serviceWorker: {
globPatterns: ['**/*.{png,svg}'],
},
};
validateServiceWorker(config, outputTarget);
expect(getServiceWorker(outputTarget).globPatterns).toEqual(['**/*.{png,svg}']);
});
it('should set globPatterns string', () => {
outputTarget = {
type: 'www',
appDir: '/www',
serviceWorker: {
globPatterns: '**/*.{png,svg}' as any,
},
};
validateServiceWorker(config, outputTarget);
expect(getServiceWorker(outputTarget).globPatterns).toEqual(['**/*.{png,svg}']);
});
it('should create default globPatterns', () => {
outputTarget = {
type: 'www',
appDir: '/www',
};
validateServiceWorker(config, outputTarget);
expect(getServiceWorker(outputTarget).globPatterns).toEqual(['*.html', '**/*.{js,css,json}']);
});
it('should create default sw config when www type and prod mode', () => {
outputTarget = {
type: 'www',
appDir: '/www',
};
validateServiceWorker(config, outputTarget);
expect(outputTarget.serviceWorker).not.toBe(null);
});
it('should not create default sw config when www type and devMode', () => {
outputTarget = {
type: 'www',
appDir: '/www',
};
config.devMode = true;
validateServiceWorker(config, outputTarget);
expect(outputTarget.serviceWorker).toBe(null);
});
it('should create default sw config when true boolean, even if devMode', () => {
outputTarget = {
type: 'www',
appDir: '/www',
serviceWorker: true as any,
};
config.devMode = true;
validateServiceWorker(config, outputTarget);
expect(outputTarget.serviceWorker).not.toBe(true);
});
it('should not create sw config when in devMode', () => {
outputTarget = {
type: 'www',
appDir: '/www',
serviceWorker: true as any,
};
config.devMode = true;
validateServiceWorker(config, outputTarget);
expect(outputTarget.serviceWorker).toBe(null);
});
it('should create sw config when in devMode if flag serviceWorker', () => {
outputTarget = {
type: 'www',
appDir: '/www',
serviceWorker: true as any,
};
config.devMode = true;
config.flags.serviceWorker = true;
validateServiceWorker(config, outputTarget);
expect(outputTarget.serviceWorker).not.toBe(null);
});
it('should stay null', () => {
outputTarget = {
type: 'www',
serviceWorker: null,
};
validateServiceWorker(config, outputTarget);
expect(outputTarget.serviceWorker).toBe(null);
});
it('should stay false', () => {
outputTarget = {
type: 'www',
serviceWorker: false,
};
validateServiceWorker(config, outputTarget);
expect(outputTarget.serviceWorker).toBe(false);
});
});
================================================
FILE: src/compiler/config/test/validate-stats.spec.ts
================================================
import type * as d from '@stencil/core/declarations';
import { mockConfig, mockLoadConfigInit } from '@stencil/core/testing';
import { validateConfig } from '../validate-config';
describe('validateStats', () => {
let userConfig: d.Config;
beforeEach(() => {
userConfig = mockConfig();
});
it('adds stats from flags, w/ no outputTargets', () => {
// the flags field is expected to have been set by the mock creation function for unvalidated configs, hence the
// bang operator
userConfig.flags!.stats = true;
const { config } = validateConfig(userConfig, mockLoadConfigInit());
const o = config.outputTargets.find((o) => o.type === 'stats') as d.OutputTargetStats;
expect(o).toBeDefined();
expect(o.file).toContain('stencil-stats.json');
});
it('uses stats config, custom path', () => {
userConfig.outputTargets = [
{
type: 'stats',
file: 'custom-path.json',
} as d.OutputTargetStats,
];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
const o = config.outputTargets.find((o) => o.type === 'stats') as d.OutputTargetStats;
expect(o).toBeDefined();
expect(o.file).toContain('custom-path.json');
});
it('uses stats config, defaults file', () => {
userConfig.outputTargets = [
{
type: 'stats',
},
];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
const o = config.outputTargets.find((o) => o.type === 'stats') as d.OutputTargetStats;
expect(o).toBeDefined();
expect(o.file).toContain('stencil-stats.json');
});
it('default no stats', () => {
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.outputTargets.some((o) => o.type === 'stats')).toBe(false);
});
it('adds stats from flags with custom path string', () => {
// Test --stats dist/stats.json behavior
userConfig.flags!.stats = 'dist/custom-stats.json';
const { config } = validateConfig(userConfig, mockLoadConfigInit());
const o = config.outputTargets.find((o) => o.type === 'stats') as d.OutputTargetStats;
expect(o).toBeDefined();
expect(o.file).toContain('dist/custom-stats.json');
});
it('adds stats from flags with custom path (absolute)', () => {
// Test --stats /tmp/stats.json behavior
userConfig.flags!.stats = '/tmp/absolute-stats.json';
const { config } = validateConfig(userConfig, mockLoadConfigInit());
const o = config.outputTargets.find((o) => o.type === 'stats') as d.OutputTargetStats;
expect(o).toBeDefined();
expect(o.file).toBe('/tmp/absolute-stats.json');
});
it('flags stats path takes precedence over default when no outputTarget', () => {
// When --stats has a path, it should be used instead of the default
userConfig.flags!.stats = 'custom-location/stats.json';
const { config } = validateConfig(userConfig, mockLoadConfigInit());
const o = config.outputTargets.find((o) => o.type === 'stats') as d.OutputTargetStats;
expect(o).toBeDefined();
expect(o.file).toContain('custom-location/stats.json');
expect(o.file).not.toContain('stencil-stats.json');
});
it('does not override existing stats outputTarget when flag has path', () => {
// When there's already a stats outputTarget in config, flag should not add another
userConfig.outputTargets = [
{
type: 'stats',
file: 'config-defined.json',
} as d.OutputTargetStats,
];
userConfig.flags!.stats = 'flag-defined.json';
const { config } = validateConfig(userConfig, mockLoadConfigInit());
const statsTargets = config.outputTargets.filter((o) => o.type === 'stats');
expect(statsTargets.length).toBe(1);
expect(statsTargets[0].file).toContain('config-defined.json');
});
});
================================================
FILE: src/compiler/config/test/validate-testing.spec.ts
================================================
import type * as d from '@stencil/core/declarations';
import { mockCompilerSystem, mockLoadConfigInit, mockLogger } from '@stencil/core/testing';
import { join } from '@utils';
import path from 'path';
import { ConfigFlags, createConfigFlags } from '../../../cli/config-flags';
import { validateConfig } from '../validate-config';
describe('validateTesting', () => {
// use Node's resolve() here to simulate a user using either Win/Posix separators (depending on the platform these
// tests are run on)
const ROOT = path.resolve('/');
const sys = mockCompilerSystem();
const logger = mockLogger();
let userConfig: d.Config;
let flags: ConfigFlags;
beforeEach(() => {
flags = createConfigFlags();
userConfig = {
sys: sys as any,
logger: logger,
// use Node's join() here to simulate a user using either Win/Posix separators (depending on the platform these
// tests are run on) for their input
rootDir: path.join(ROOT, 'User', 'some', 'path'),
srcDir: path.join(ROOT, 'User', 'some', 'path', 'src'),
flags,
namespace: 'Testing',
// use Node's join() here to simulate a user using either Win/Posix separators (depending on the platform these
// tests are run on) for their input
configPath: path.join(ROOT, 'User', 'some', 'path', 'stencil.config.ts'),
};
userConfig.outputTargets = [
{
type: 'www',
// use Node's join() here to simulate a user using either Win/Posix separators (depending on the platform these
// tests are run on) for their input
dir: path.join(ROOT, 'www'),
} as any as d.OutputTargetStats,
];
});
describe('no testing flags', () => {
it('returns an empty testing config when no testing config nor testing flags are provided', () => {
userConfig.flags = { ...flags, e2e: false, spec: false };
delete userConfig.testing;
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing).toEqual({});
});
it('returns the provided testing config when neither testing flag is provided', () => {
const testingConfig: d.TestingConfig = {
bail: false,
};
userConfig.flags = { ...flags, e2e: false, spec: false };
userConfig.testing = testingConfig;
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing).toEqual(testingConfig);
});
});
describe('browserHeadless', () => {
const originalCI = process.env.CI;
beforeEach(() => {
delete process.env.CI;
});
afterEach(() => {
process.env.CI = originalCI;
});
describe("using 'headless' value from cli", () => {
it.each([false, 'shell'])('sets browserHeadless to %s', (headless) => {
userConfig.flags = { ...flags, e2e: true, headless };
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.browserHeadless).toBe(headless);
});
it('throws if browser headless is set to deprecated value `true`', () => {
userConfig.flags = { ...flags, e2e: true, headless: true };
expect(() => validateConfig(userConfig, mockLoadConfigInit())).toThrow(
'Setting "browserHeadless" config to `true` is not supported anymore, please set it to "shell"!',
);
});
it('defaults to "shell" outside of CI', () => {
userConfig.flags = { ...flags, e2e: true };
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.browserHeadless).toBe('shell');
});
});
describe('with ci enabled', () => {
it("forces using the shell headless mode when 'headless: false'", () => {
userConfig.flags = { ...flags, ci: true, e2e: true, headless: false };
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.browserHeadless).toBe('shell');
});
it('allows the shell headless mode to be used', () => {
userConfig.flags = { ...flags, ci: true, e2e: true, headless: 'shell' };
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.browserHeadless).toBe('shell');
});
});
describe('`testing` configuration', () => {
beforeEach(() => {
userConfig.flags = { ...flags, e2e: true, headless: undefined };
});
it.each([false, 'shell'])(
'uses %s browserHeadless mode from testing config',
(browserHeadlessValue) => {
userConfig.testing = { browserHeadless: browserHeadlessValue };
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.browserHeadless).toBe(browserHeadlessValue);
},
);
it('throws if browser headless is set to deprecated value `true`', () => {
userConfig.testing = { browserHeadless: true };
expect(() => validateConfig(userConfig, mockLoadConfigInit())).toThrow(
'Setting "browserHeadless" config to `true` is not supported anymore, please set it to "shell"!',
);
});
it('defaults the headless mode to "shell" when browserHeadless is not provided', () => {
userConfig.testing = {};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.browserHeadless).toBe('shell');
});
});
});
describe('devTools', () => {
const originalCI = process.env.CI;
beforeEach(() => {
delete process.env.CI;
});
afterEach(() => {
process.env.CI = originalCI;
});
it('ignores devTools settings if CI is enabled', () => {
userConfig.flags = { ...flags, ci: true, devtools: true, e2e: true };
userConfig.testing = {};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.browserDevtools).toBeUndefined();
});
it('sets browserDevTools to true when the devtools flag is set', () => {
userConfig.flags = { ...flags, devtools: true, e2e: true };
userConfig.testing = {};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.browserDevtools).toBe(true);
// browserHeadless must be false to enabled dev tools (which are headful by definition)
expect(config.testing.browserHeadless).toBe(false);
});
it("sets browserDevTools to true when set in a project's config", () => {
userConfig.flags = { ...flags, devtools: false, e2e: true };
userConfig.testing = { browserDevtools: true };
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.browserDevtools).toBe(true);
// browserHeadless must be false to enabled dev tools (which are headful by definition)
expect(config.testing.browserHeadless).toBe(false);
});
});
describe('browserWaitUntil', () => {
it('sets the default to "load" if no value is provided', () => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.browserWaitUntil).toBe('load');
});
it('does not override a provided value', () => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
browserWaitUntil: 'domcontentloaded',
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.browserWaitUntil).toBe('domcontentloaded');
});
});
describe('browserArgs', () => {
const originalCI = process.env.CI;
beforeEach(() => {
delete process.env.CI;
});
afterEach(() => {
process.env.CI = originalCI;
});
it('does not add duplicate default fields', () => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
browserArgs: ['--unique', '--font-render-hinting=medium'],
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.browserArgs).toEqual(['--unique', '--font-render-hinting=medium', '--incognito']);
});
describe('adds default browser args', () => {
const originalCI = process.env.CI;
beforeAll(() => {
delete process.env.CI;
});
afterAll(() => {
process.env.CI = originalCI;
});
it('adds default browser args when not in CI', () => {
userConfig.flags = { ...flags, e2e: true };
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.browserArgs).toEqual(['--font-render-hinting=medium', '--incognito']);
});
});
it("adds additional browser args when the 'ci' flag is set", () => {
userConfig.flags = { ...flags, ci: true, e2e: true };
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.browserArgs).toEqual([
'--font-render-hinting=medium',
'--incognito',
'--no-sandbox',
'--disable-setuid-sandbox',
'--disable-dev-shm-usage',
]);
});
describe('adds additional browser args when process.env.CI is set', () => {
const originalCI = process.env.CI;
beforeAll(() => {
process.env.CI = 'true';
});
afterAll(() => {
process.env.CI = originalCI;
});
it('adds default browser args when CI is set', () => {
userConfig.flags = { ...flags, ci: true, e2e: true };
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.browserArgs).toEqual([
'--font-render-hinting=medium',
'--incognito',
'--no-sandbox',
'--disable-setuid-sandbox',
'--disable-dev-shm-usage',
]);
});
});
});
describe('browserArgs in CI', () => {
const originalCI = process.env.CI;
beforeEach(() => {
process.env.CI = 'true';
});
afterEach(() => {
process.env.CI = originalCI;
});
it("adds additional browser args when 'CI' environment variable is set", () => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
browserArgs: ['--unique', '--font-render-hinting=medium'],
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.browserArgs).toEqual([
'--unique',
'--font-render-hinting=medium',
'--incognito',
'--no-sandbox',
'--disable-setuid-sandbox',
'--disable-dev-shm-usage',
]);
});
});
describe('screenshotConnector', () => {
it('assigns the screenshotConnector value from the provided flags', () => {
// use Node's join() here to simulate a user using either Win/Posix separators (depending on the platform these
// tests are run on) for their input
userConfig.flags = { ...flags, e2e: true, screenshotConnector: path.join(ROOT, 'mock', 'path') };
userConfig.testing = { screenshotConnector: path.join(ROOT, 'another', 'mock', 'path') };
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.screenshotConnector).toBe(join(ROOT, 'mock', 'path'));
});
it("uses the config's root dir to make the screenshotConnector path absolute", () => {
// use Node's join() here to simulate a user using either Win/Posix separators (depending on the platform these
// tests are run on) for their input
userConfig.flags = { ...flags, e2e: true, screenshotConnector: path.join('mock', 'path') };
userConfig.testing = { screenshotConnector: path.join('another', 'mock', 'path') };
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.screenshotConnector).toBe(join(ROOT, 'User', 'some', 'path', 'mock', 'path'));
});
it('sets screenshotConnector if a non-string is provided', () => {
userConfig.flags = { ...flags, e2e: true };
// the nature of this test is to evaluate a non-string, hence the type assertion
userConfig.testing = { screenshotConnector: true as unknown as string };
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.screenshotConnector).toBe(join('screenshot', 'local-connector.js'));
});
});
describe('screenshotTimeout', () => {
it('sets screenshotTimeout to null if not provided', () => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.screenshotTimeout).toEqual(null);
});
it('sets screenshotTimeout to null if it has an unexpected value', () => {
userConfig.flags = { ...flags, e2e: true };
// @ts-expect-error - the nature of this test requires a non-string value
userConfig.testing = { screenshotTimeout: '4s' };
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.screenshotTimeout).toEqual(null);
});
it('keeps the value if set correctly', () => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = { screenshotTimeout: 4000 };
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.screenshotTimeout).toEqual(4000);
});
});
describe('testPathIgnorePatterns', () => {
it('does not alter a provided testPathIgnorePatterns', () => {
userConfig.flags = { ...flags, e2e: true };
// use Node's join() here to simulate a user using either Win/Posix separators (depending on the platform these
// tests are run on) for their input
const mockPath1 = path.join('this', 'is', 'a', 'mock', 'path');
const mockPath2 = path.join('this', 'is', 'another', 'mock', 'path');
userConfig.testing = { testPathIgnorePatterns: [mockPath1, mockPath2] };
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.testPathIgnorePatterns).toEqual([mockPath1, mockPath2]);
});
it('sets the default testPathIgnorePatterns if no array is provided', () => {
userConfig.flags = { ...flags, e2e: true };
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.testPathIgnorePatterns).toEqual([
join(ROOT, 'User', 'some', 'path', '.vscode'),
join(ROOT, 'User', 'some', 'path', '.stencil'),
join(ROOT, 'User', 'some', 'path', 'node_modules'),
// use Node's join() here as the normalization process doesn't necessarily occur for this field
path.join(ROOT, 'www'),
]);
});
it('sets the default testPathIgnorePatterns with custom outputTargets', () => {
userConfig.flags = { ...flags, e2e: true };
userConfig.outputTargets = [
{ type: 'dist', dir: 'dist-folder' },
{ type: 'www', dir: 'www-folder' },
{ type: 'docs-readme', dir: 'docs' },
];
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.testPathIgnorePatterns).toEqual([
join(ROOT, 'User', 'some', 'path', '.vscode'),
join(ROOT, 'User', 'some', 'path', '.stencil'),
join(ROOT, 'User', 'some', 'path', 'node_modules'),
join(ROOT, 'User', 'some', 'path', 'www-folder'),
join(ROOT, 'User', 'some', 'path', 'dist-folder'),
]);
});
});
describe('preset', () => {
it.each([null, true])("uses stencil's default preset if a non-string (%s) is provided", (nonStringPreset) => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
// the nature of this test requires a non-string value, hence the type assertion
preset: nonStringPreset as unknown as string,
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
// 'testing' is the internal directory where `jest-preset.js` can be found
expect(config.testing.preset).toEqual('testing');
});
it('forces a provided preset path to be absolute', () => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
// use Node's join() here to simulate a user using either Win/Posix separators (depending on the platform these
// tests are run on) for their input
preset: path.join('mock', 'path'),
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.preset).toEqual(join(ROOT, 'User', 'some', 'path', 'mock', 'path'));
});
it('does not change an already absolute preset path', () => {
userConfig.flags = { ...flags, e2e: true };
// use Node's join() here to simulate a user using either Win/Posix separators (depending on the platform these
// tests are run on) for their input
const presetPath = path.join(ROOT, 'mock', 'path');
userConfig.testing = {
preset: presetPath,
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
// per the test name, we should not change an already absolute path - assert against the preset path that was
// generated using Node's join()
expect(config.testing.preset).toEqual(presetPath);
});
});
describe('setupFilesAfterEnv', () => {
it.each([null, true])('forces a non-array (%s) of setup files to a default', (nonSetupFiles) => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
// the nature of this test requires a non-string value, hence the type assertion
setupFilesAfterEnv: nonSetupFiles as unknown as string[],
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
// 'testing' is the internal directory where the default setup file can be found
expect(config.testing.setupFilesAfterEnv).toEqual([join('testing', 'jest-setuptestframework.js')]);
});
it.each([[[]], [['mock-setup-file.js']]])(
"prepends stencil's default file to an array: %s",
(setupFilesAfterEnv) => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
setupFilesAfterEnv: [...setupFilesAfterEnv],
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.setupFilesAfterEnv).toEqual([
// 'testing' is the internal directory where the default setup file can be found
join('testing', 'jest-setuptestframework.js'),
...setupFilesAfterEnv,
]);
},
);
});
describe('testEnvironment', () => {
it('sets a relative testEnvironment to absolute', () => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
testEnvironment: './rel-path.js',
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(path.isAbsolute(config.testing.testEnvironment)).toBe(true);
expect(path.basename(config.testing.testEnvironment)).toEqual('rel-path.js');
});
it('allows a node module testEnvironment', () => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
testEnvironment: 'jsdom',
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.testEnvironment).toEqual('jsdom');
});
it('does nothing for an empty testEnvironment', () => {
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.testEnvironment).toBeUndefined();
});
});
describe('allowableMismatchedPixels', () => {
it.each([0, 123])('does nothing is a non-negative number (%s) is provided', (pixelCount) => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
allowableMismatchedPixels: pixelCount,
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.allowableMismatchedPixels).toBe(pixelCount);
});
it('creates an error if a negative number is provided', () => {
const pixelCount = -1;
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
allowableMismatchedPixels: pixelCount,
};
const { config, diagnostics } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.allowableMismatchedPixels).toBe(pixelCount);
expect(diagnostics).toHaveLength(1);
expect(diagnostics[0]).toEqual({
absFilePath: undefined,
header: 'Build Error',
level: 'error',
lines: [],
messageText: 'allowableMismatchedPixels must be a value that is 0 or greater',
relFilePath: undefined,
type: 'build',
});
});
it.each([true, null])('defaults to a reasonable value if a non-number (%s) is provided', (pixelCount) => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
// the nature of this test requires using a non-number, hence th type assertion
allowableMismatchedPixels: pixelCount as unknown as number,
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.allowableMismatchedPixels).toBe(100);
});
});
describe('allowableMismatchedRatio', () => {
it.each([-0, 0, 0.5, 1.0])(
'does nothing if a value between 0 and 1 is provided (%s)',
(allowableMismatchedRatio) => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
allowableMismatchedRatio,
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.allowableMismatchedRatio).toBe(allowableMismatchedRatio);
},
);
it.each([-1, -0.1, 1.1, 2])(
'creates an error if a number outside 0 and 1 is provided (%s)',
(allowableMismatchedRatio) => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
allowableMismatchedRatio,
};
const { config, diagnostics } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.allowableMismatchedRatio).toBe(allowableMismatchedRatio);
expect(diagnostics).toHaveLength(1);
expect(diagnostics[0]).toEqual({
absFilePath: undefined,
header: 'Build Error',
level: 'error',
lines: [],
messageText: 'allowableMismatchedRatio must be a value ranging from 0 to 1',
relFilePath: undefined,
type: 'build',
});
},
);
it.each([true, null])('does nothing when a non-number (%s) is provided', (allowableMismatchedRatio) => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
// the nature of this test requires using a non-number, hence th type assertion
allowableMismatchedRatio: allowableMismatchedRatio as unknown as number,
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.allowableMismatchedRatio).toBe(allowableMismatchedRatio);
});
});
describe('pixelmatchThreshold', () => {
it.each([-0, 0, 0.5, 1.0])('does nothing if a value between 0 and 1 is provided (%s)', (pixelmatchThreshold) => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
pixelmatchThreshold,
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.pixelmatchThreshold).toBe(pixelmatchThreshold);
});
it.each([-0.1, -1, 1.1, 2])(
'creates an error if a number outside 0 and 1 is provided (%s)',
(pixelmatchThreshold) => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
pixelmatchThreshold,
};
const { config, diagnostics } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.pixelmatchThreshold).toBe(pixelmatchThreshold);
expect(diagnostics).toHaveLength(1);
expect(diagnostics[0]).toEqual({
absFilePath: undefined,
header: 'Build Error',
level: 'error',
lines: [],
messageText: 'pixelmatchThreshold must be a value ranging from 0 to 1',
relFilePath: undefined,
type: 'build',
});
},
);
it.each([true, null])('defaults to a reasonable value if a non-number (%s) is provided', (pixelmatchThreshold) => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
// the nature of this test requires using a non-number, hence th type assertion
pixelmatchThreshold: pixelmatchThreshold as unknown as number,
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.allowableMismatchedPixels).toBe(100);
});
});
describe('testRegex', () => {
let testRegex: RegExp;
beforeEach(() => {
userConfig.flags = { ...flags, spec: true };
const { testing: testConfig } = validateConfig(userConfig, mockLoadConfigInit()).config;
const testRegexSetting = testConfig?.testRegex;
if (!testRegexSetting) {
throw new Error('No testRegex was found in the Stencil TestingConfig. Failing test.');
}
testRegex = new RegExp(testRegexSetting[0]);
});
describe('test.* extensions', () => {
it.each([
'my-component.test.ts',
'my-component.test.tsx',
'my-component.test.js',
'my-component.test.jsx',
'some/path/test.ts',
'some/path/test.tsx',
'some/path/test.js',
'some/path/test.jsx',
])(`matches the file '%s'`, (filename) => {
expect(testRegex.test(filename)).toBe(true);
});
it.each([
'my-component.test.ts.snap',
'my-component.test.tsx.snap',
'my-component.test.js.snap',
'my-component.test.jsx.snap',
'my-component-test.ts',
'my-component-test.tsx',
'my-component-test.js',
'my-component-test.jsx',
'my-component.test.t',
'my-component.test.j',
])(`doesn't match the file '%s'`, (filename) => {
expect(testRegex.test(filename)).toBe(false);
});
});
describe('spec.* extensions', () => {
it.each([
'my-component.spec.ts',
'my-component.spec.tsx',
'my-component.spec.js',
'my-component.spec.jsx',
'some/path/spec.ts',
'some/path/spec.tsx',
'some/path/spec.js',
'some/path/spec.jsx',
])(`matches the file '%s'`, (filename) => {
expect(testRegex.test(filename)).toBe(true);
});
it.each([
'my-component.spec.ts.snap',
'my-component.spec.tsx.snap',
'my-component.spec.js.snap',
'my-component.spec.jsx.snap',
'my-component-spec.ts',
'my-component-spec.tsx',
'my-component-spec.js',
'my-component-spec.jsx',
'my-component.spec.t',
'my-component.spec.j',
])(`doesn't match the file '%s'`, (filename) => {
expect(testRegex.test(filename)).toBe(false);
});
});
describe('e2e.* extensions', () => {
it.each([
'my-component.e2e.ts',
'my-component.e2e.tsx',
'my-component.e2e.js',
'my-component.e2e.jsx',
'some/path/e2e.ts',
'some/path/e2e.tsx',
'some/path/e2e.js',
'some/path/e2e.jsx',
])(`matches the file '%s'`, (filename) => {
expect(testRegex.test(filename)).toBe(true);
});
it.each([
'my-component.e2e.ts.snap',
'my-component.e2e.tsx.snap',
'my-component.e2e.js.snap',
'my-component.e2e.jsx.snap',
'my-component-e2e.ts',
'my-component-e2e.tsx',
'my-component-e2e.js',
'my-component-e2e.jsx',
'my-component.e2e.t',
'my-component.e2e.j',
])(`doesn't match the file '%s'`, (filename) => {
expect(testRegex.test(filename)).toBe(false);
});
});
});
describe('testMatch', () => {
it('removes testRegex from the config when testMatch is an array', () => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
testMatch: ['mockMatcher'],
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.testMatch).toEqual(['mockMatcher']);
expect(config.testing.testRegex).toBeUndefined();
});
it('removes testMatch from the config when testRegex is a string', () => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
testMatch: undefined,
testRegex: ['/regexStr/'],
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.testMatch).toBeUndefined();
expect(config.testing.testRegex).toEqual(['/regexStr/']);
});
it('transforms testRegex to an array if passed in as string', () => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
testMatch: undefined,
// @ts-expect-error invalid type because of type update
testRegex: '/regexStr/',
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.testMatch).toBeUndefined();
expect(config.testing.testRegex).toEqual(['/regexStr/']);
});
});
describe('runner', () => {
it('does nothing if the runner property is a string', () => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
runner: 'my-runner.js',
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.runner).toEqual('my-runner.js');
});
it('sets the runner if a non-string value is provided', () => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
runner: undefined,
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
// 'testing' is the internal directory where the default runner file can be found
expect(config.testing.runner).toEqual(join('testing', 'jest-runner.js'));
});
});
describe('waitBeforeScreenshot', () => {
it.each([-0, 0, 0.5, 1.0])('does nothing for a non-negative value (%s)', (waitBeforeScreenshot) => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
waitBeforeScreenshot,
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.waitBeforeScreenshot).toBe(waitBeforeScreenshot);
});
it('creates an error if the value provided is negative', () => {
const waitBeforeScreenshot = -1;
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
waitBeforeScreenshot,
};
const { config, diagnostics } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.waitBeforeScreenshot).toBe(waitBeforeScreenshot);
expect(diagnostics).toHaveLength(1);
expect(diagnostics[0]).toEqual({
absFilePath: undefined,
header: 'Build Error',
level: 'error',
lines: [],
messageText: 'waitBeforeScreenshot must be a value that is 0 or greater',
relFilePath: undefined,
type: 'build',
});
});
it.each([true, null])('defaults to a reasonable value if a non-number (%s) is provided', (waitBeforeScreenshot) => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
// the nature of this test requires using a non-number, hence the type assertion
pixelmatchThreshold: waitBeforeScreenshot as unknown as number,
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.waitBeforeScreenshot).toBe(10);
});
});
describe('emulate', () => {
it.each([[undefined], [[]]])('provides a reasonable default for %s', (emulate) => {
userConfig.flags = { ...flags, e2e: true };
userConfig.testing = {
emulate,
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.emulate).toEqual([
{
userAgent: 'default',
viewport: {
width: 600,
height: 600,
deviceScaleFactor: 1,
isMobile: false,
hasTouch: false,
isLandscape: false,
},
},
]);
});
it('does nothing when a non-zero length array is provided', () => {
userConfig.flags = { ...flags, e2e: true };
const emulateConfig: d.EmulateConfig = {
userAgent: 'mockAgent',
viewport: {
width: 100,
height: 100,
deviceScaleFactor: 1,
isMobile: true,
hasTouch: true,
isLandscape: false,
},
};
userConfig.testing = {
emulate: [emulateConfig],
};
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.testing.emulate).toEqual([emulateConfig]);
});
});
});
================================================
FILE: src/compiler/config/test/validate-workers.spec.ts
================================================
import type * as d from '@stencil/core/declarations';
import { mockLoadConfigInit, mockLogger } from '@stencil/core/testing';
import path from 'path';
import { createConfigFlags } from '../../../cli/config-flags';
import { validateConfig } from '../validate-config';
describe('validate-workers', () => {
let userConfig: d.Config;
const logger = mockLogger();
beforeEach(() => {
userConfig = {
sys: {
path: path,
} as any,
logger: logger,
rootDir: '/',
namespace: 'Testing',
};
});
it('set maxConcurrentWorkers, but dont let it go under 0', () => {
userConfig.maxConcurrentWorkers = -1;
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.maxConcurrentWorkers).toBe(0);
});
it('set maxConcurrentWorkers from ci flags', () => {
userConfig.flags = createConfigFlags({
ci: true,
});
userConfig.maxConcurrentWorkers = 2;
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.maxConcurrentWorkers).toBe(4);
});
it('set maxConcurrentWorkers from flags', () => {
userConfig.flags = createConfigFlags({
maxWorkers: 1,
});
userConfig.maxConcurrentWorkers = 4;
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.maxConcurrentWorkers).toBe(1);
});
it('set maxConcurrentWorkers', () => {
userConfig.maxConcurrentWorkers = 4;
const { config } = validateConfig(userConfig, mockLoadConfigInit());
expect(config.maxConcurrentWorkers).toBe(4);
});
});
================================================
FILE: src/compiler/config/transpile-options.ts
================================================
import { isString } from '@utils';
import type { CompilerOptions } from 'typescript';
import type {
CompilerSystem,
Config,
ImportData,
TransformCssToEsmInput,
TransformOptions,
TranspileOptions,
TranspileResults,
} from '../../declarations';
import { STENCIL_INTERNAL_CLIENT_ID } from '../bundle/entry-alias-ids';
import { parseImportPath } from '../transformers/stencil-import-path';
export const getTranspileResults = (code: string, input: TranspileOptions) => {
if (!isString(input.file)) {
input.file = 'module.tsx';
}
const parsedImport = parseImportPath(input.file);
const results: TranspileResults = {
code: typeof code === 'string' ? code : '',
data: [],
diagnostics: [],
inputFileExtension: parsedImport.ext,
inputFilePath: input.file,
imports: [],
map: null,
outputFilePath: null,
};
return {
importData: parsedImport.data,
results,
};
};
const transpileCtx = { sys: null as CompilerSystem };
/**
* Configuration necessary for transpilation
*/
interface TranspileConfig {
compileOpts: TranspileOptions;
config: Config;
transformOpts: TransformOptions;
}
/**
* Get configuration necessary to carry out transpilation, including a Stencil
* configuration, transformation options, and transpilation options.
*
* @param input options for Stencil's transpiler (string-to-string compiler)
* @returns the options and configuration necessary for transpilation
*/
export const getTranspileConfig = (input: TranspileOptions): TranspileConfig => {
if (input.sys) {
transpileCtx.sys = input.sys;
} else if (!transpileCtx.sys) {
transpileCtx.sys = require('../sys/node/index.js').createNodeSys();
}
const compileOpts: TranspileOptions = {
componentExport: getTranspileConfigOpt(input.componentExport, VALID_EXPORT, 'customelement'),
componentMetadata: getTranspileConfigOpt(input.componentMetadata, VALID_METADATA, null),
coreImportPath: isString(input.coreImportPath) ? input.coreImportPath : STENCIL_INTERNAL_CLIENT_ID,
currentDirectory: isString(input.currentDirectory)
? input.currentDirectory
: transpileCtx.sys.getCurrentDirectory(),
file: input.file,
proxy: getTranspileConfigOpt(input.proxy, VALID_PROXY, 'defineproperty'),
module: getTranspileConfigOpt(input.module, VALID_MODULE, 'esm'),
sourceMap: input.sourceMap === 'inline' ? 'inline' : input.sourceMap !== false,
style: getTranspileConfigOpt(input.style, VALID_STYLE, 'static'),
styleImportData: getTranspileConfigOpt(input.styleImportData, VALID_STYLE_IMPORT_DATA, 'queryparams'),
target: getTranspileConfigOpt(input.target, VALID_TARGET, 'latest'),
};
const tsCompilerOptions: CompilerOptions = {
// ensure we uses legacy decorators
experimentalDecorators: true,
// best we always set this to true
allowSyntheticDefaultImports: true,
// best we always set this to true
esModuleInterop: true,
// always get source maps
sourceMap: compileOpts.sourceMap !== false,
// isolated per file transpiling
isolatedModules: true,
// transpileModule does not write anything to disk so there is no need to verify that there are no conflicts between input and output paths.
suppressOutputPathCheck: true,
// Filename can be non-ts file.
allowNonTsExtensions: true,
// We are not returning a sourceFile for lib file when asked by the program,
// so pass --noLib to avoid reporting a file not found error.
noLib: true,
noResolve: true,
// NOTE: "module" and "target" configs will be set later
// after the "ts" object has been loaded
};
if (isString(input.baseUrl)) {
compileOpts.baseUrl = input.baseUrl;
tsCompilerOptions.baseUrl = compileOpts.baseUrl;
}
if (input.paths) {
compileOpts.paths = { ...input.paths };
tsCompilerOptions.paths = { ...compileOpts.paths };
}
if (input.jsx !== undefined) {
tsCompilerOptions.jsx = input.jsx;
}
if (isString(input.jsxImportSource)) {
tsCompilerOptions.jsxImportSource = input.jsxImportSource;
}
const transformOpts: TransformOptions = {
coreImportPath: compileOpts.coreImportPath,
componentExport: compileOpts.componentExport as any,
componentMetadata: compileOpts.componentMetadata as any,
currentDirectory: compileOpts.currentDirectory,
isolatedModules: true,
module: compileOpts.module as any,
proxy: compileOpts.proxy as any,
file: compileOpts.file,
style: compileOpts.style as any,
styleImportData: compileOpts.styleImportData as any,
target: compileOpts.target as any,
};
const config: Config = {
_isTesting: true,
devMode: true,
enableCache: false,
minifyCss: true,
minifyJs: false,
rootDir: compileOpts.currentDirectory,
srcDir: compileOpts.currentDirectory,
sys: transpileCtx.sys,
transformAliasedImportPaths: input.transformAliasedImportPaths,
tsCompilerOptions,
validateTypes: false,
};
return {
compileOpts,
config,
transformOpts,
};
};
export const getTranspileCssConfig = (
compileOpts: TranspileOptions,
importData: ImportData,
results: TranspileResults,
) => {
const transformInput: TransformCssToEsmInput = {
file: results.inputFilePath,
input: results.code,
tag: importData && importData.tag,
tags: [...(compileOpts.tagsToTransform || importData?.tag)],
addTagTransformers: compileOpts && compileOpts.additionalTagTransformers === true,
encapsulation: importData && importData.encapsulation,
mode: importData && importData.mode,
sourceMap: compileOpts.sourceMap !== false,
minify: false,
autoprefixer: false,
module: compileOpts.module,
styleImportData: compileOpts.styleImportData,
};
return transformInput;
};
const getTranspileConfigOpt = (value: any, validValues: Set, defaultValue: string) => {
if (value === null || value === 'null') {
return null;
}
value = isString(value) ? value.toLowerCase().trim() : null;
if (validValues.has(value)) {
return value;
}
return defaultValue;
};
const VALID_EXPORT = new Set(['customelement', 'module']);
const VALID_METADATA = new Set(['compilerstatic', null]);
const VALID_MODULE = new Set(['cjs', 'esm']);
const VALID_PROXY = new Set(['defineproperty', null]);
const VALID_STYLE = new Set(['static']);
const VALID_STYLE_IMPORT_DATA = new Set(['queryparams']);
const VALID_TARGET = new Set(['latest', 'esnext', 'es2020', 'es2019', 'es2018', 'es2017', 'es2016', 'es2015', 'es5']);
================================================
FILE: src/compiler/config/validate-config.ts
================================================
import { createNodeLogger, createNodeSys } from '@sys-api-node';
import { buildError, buildWarn, isBoolean, isNumber, isString, sortBy } from '@utils';
import {
ConfigBundle,
ConfigExtras,
Diagnostic,
LoadConfigInit,
LogLevel,
UnvalidatedConfig,
ValidatedConfig,
} from '../../declarations';
import { setBooleanConfig } from './config-utils';
import {
DEFAULT_DEV_MODE,
DEFAULT_HASHED_FILENAME_LENGTH,
MAX_HASHED_FILENAME_LENGTH,
MIN_HASHED_FILENAME_LENGTH,
} from './constants';
import { validateOutputTargets } from './outputs';
import { validateDevServer } from './validate-dev-server';
import { validateDocs } from './validate-docs';
import { validateHydrated } from './validate-hydrated';
import { validateDistNamespace } from './validate-namespace';
import { validateNamespace } from './validate-namespace';
import { validatePaths } from './validate-paths';
import { validatePlugins } from './validate-plugins';
import { validateRollupConfig } from './validate-rollup-config';
import { validateTesting } from './validate-testing';
import { validateWorkers } from './validate-workers';
/**
* Represents the results of validating a previously unvalidated configuration
*/
type ConfigValidationResults = {
/**
* The validated configuration, with well-known default values set if they weren't previously provided
*/
config: ValidatedConfig;
/**
* A collection of errors and warnings that occurred during the configuration validation process
*/
diagnostics: Diagnostic[];
};
/**
* We never really want to re-run validation for a Stencil configuration.
* Besides the cost of doing so, our validation pipeline is unfortunately not
* idempotent, so we want to have a guarantee that even if we call
* {@link validateConfig} in a few places that the same configuration object
* won't be passed through multiple times. So we cache the result of our work
* here.
*/
let CACHED_VALIDATED_CONFIG: ValidatedConfig | null = null;
/**
* Validate a Config object, ensuring that all its field are present and
* consistent with our expectations. This function transforms an
* {@link UnvalidatedConfig} to a {@link ValidatedConfig}.
*
* **NOTE**: this function _may_ return a previously-cached configuration
* object. It will do so if the cached object is `===` to the one passed in.
*
* @param userConfig an unvalidated config that we've gotten from a user
* @param bootstrapConfig the initial configuration provided by the user (or
* generated by Stencil) used to bootstrap configuration loading and validation
* @returns an object with config and diagnostics props
*/
export const validateConfig = (
userConfig: UnvalidatedConfig = {},
bootstrapConfig: LoadConfigInit,
): ConfigValidationResults => {
const diagnostics: Diagnostic[] = [];
if (CACHED_VALIDATED_CONFIG !== null && CACHED_VALIDATED_CONFIG === userConfig) {
// We've previously done the work to validate a Stencil config. Since our
// overall validation pipeline is unfortunately not idempotent we do not
// want to simply validate again. Leaving aside the performance
// implications of needlessly repeating the validation, we don't want to do
// certain operations multiple times.
//
// For the sake of correctness we check both that the cache is not null and
// that it's the same object as the one passed in.
return {
config: userConfig as ValidatedConfig,
diagnostics,
};
}
const config = Object.assign({}, userConfig);
const logger = bootstrapConfig.logger || config.logger || createNodeLogger();
// flags _should_ be JSON safe here
//
// we access `'flags'` on validated config to avoid having to introduce an
// import of the CLI module
const flags: ValidatedConfig['flags'] = JSON.parse(JSON.stringify(config.flags || {}));
// default level is 'info'
let logLevel: LogLevel = 'info';
if (flags.debug || flags.verbose) {
logLevel = 'debug';
} else if (flags.logLevel) {
logLevel = flags.logLevel;
}
logger.setLevel(logLevel);
let devMode = config.devMode ?? DEFAULT_DEV_MODE;
if (flags.prod) {
devMode = false;
} else if (flags.dev) {
devMode = true;
} else if (!isBoolean(config.devMode)) {
devMode = DEFAULT_DEV_MODE;
}
const hashFileNames = config.hashFileNames ?? !devMode;
const validatedConfig: ValidatedConfig = {
devServer: {}, // assign `devServer` before spreading `config`, in the event 'devServer' is not a key on `config`
...config,
buildEs5: config.buildEs5 === true || (!devMode && config.buildEs5 === 'prod'),
devMode,
extras: config.extras || {},
flags,
generateExportMaps: isBoolean(config.generateExportMaps) ? config.generateExportMaps : false,
hashFileNames,
hashedFileNameLength: config.hashedFileNameLength ?? DEFAULT_HASHED_FILENAME_LENGTH,
hydratedFlag: validateHydrated(config),
logLevel,
logger,
minifyCss: config.minifyCss ?? !devMode,
minifyJs: config.minifyJs ?? !devMode,
outputTargets: config.outputTargets ?? [],
rollupConfig: validateRollupConfig(config),
sourceMap:
config.sourceMap === true || (devMode && (config.sourceMap === 'dev' || typeof config.sourceMap === 'undefined')),
sys: config.sys ?? bootstrapConfig.sys ?? createNodeSys({ logger }),
testing: config.testing ?? {},
docs: validateDocs(config, logger),
transformAliasedImportPaths: isBoolean(userConfig.transformAliasedImportPaths)
? userConfig.transformAliasedImportPaths
: true,
validatePrimaryPackageOutputTarget: userConfig.validatePrimaryPackageOutputTarget ?? false,
...validateNamespace(config.namespace, config.fsNamespace, diagnostics),
...validatePaths(config),
};
validatedConfig.extras.lifecycleDOMEvents = !!validatedConfig.extras.lifecycleDOMEvents;
validatedConfig.extras.scriptDataOpts = !!validatedConfig.extras.scriptDataOpts;
validatedConfig.extras.initializeNextTick = !!validatedConfig.extras.initializeNextTick;
validatedConfig.extras.tagNameTransform = !!validatedConfig.extras.tagNameTransform;
validatedConfig.extras.additionalTagTransformers =
validatedConfig.extras.additionalTagTransformers === true ||
(!devMode && validatedConfig.extras.additionalTagTransformers === 'prod');
validatedConfig.extras.addGlobalStyleToComponents = isBoolean(validatedConfig.extras.addGlobalStyleToComponents)
? validatedConfig.extras.addGlobalStyleToComponents
: 'client';
// TODO(STENCIL-914): remove when `experimentalSlotFixes` is the default behavior
// If the user set `experimentalSlotFixes` and any individual slot fix flags to `false`, we need to log a warning
// to the user that we will "override" the individual flags
if (validatedConfig.extras.experimentalSlotFixes === true) {
const possibleFlags: (keyof ConfigExtras)[] = [
'appendChildSlotFix',
'slotChildNodesFix',
'cloneNodeFix',
'scopedSlotTextContentFix',
'experimentalScopedSlotChanges',
];
const conflictingFlags = possibleFlags.filter((flag) => validatedConfig.extras[flag] === false);
if (conflictingFlags.length > 0) {
const warning = buildError(diagnostics);
warning.level = 'warn';
warning.messageText = `If the 'experimentalSlotFixes' flag is enabled it will override any slot fix flags which are disabled. In particular, the following currently-disabled flags will be ignored: ${conflictingFlags.join(
', ',
)}. Please update your Stencil config accordingly.`;
}
}
// TODO(STENCIL-914): remove `experimentalSlotFixes` when it's the default behavior
validatedConfig.extras.experimentalSlotFixes = !!validatedConfig.extras.experimentalSlotFixes;
if (validatedConfig.extras.experimentalSlotFixes === true) {
validatedConfig.extras.appendChildSlotFix = true;
validatedConfig.extras.cloneNodeFix = true;
validatedConfig.extras.slotChildNodesFix = true;
validatedConfig.extras.scopedSlotTextContentFix = true;
validatedConfig.extras.experimentalScopedSlotChanges = true;
} else {
validatedConfig.extras.appendChildSlotFix = !!validatedConfig.extras.appendChildSlotFix;
validatedConfig.extras.cloneNodeFix = !!validatedConfig.extras.cloneNodeFix;
validatedConfig.extras.slotChildNodesFix = !!validatedConfig.extras.slotChildNodesFix;
validatedConfig.extras.scopedSlotTextContentFix = !!validatedConfig.extras.scopedSlotTextContentFix;
// TODO(STENCIL-1086): remove this option when it's the default behavior
validatedConfig.extras.experimentalScopedSlotChanges = !!validatedConfig.extras.experimentalScopedSlotChanges;
}
setBooleanConfig(validatedConfig, 'watch', 'watch', false);
setBooleanConfig(validatedConfig, 'buildDocs', 'docs', !validatedConfig.devMode);
setBooleanConfig(validatedConfig, 'buildDist', 'esm', !validatedConfig.devMode || !!validatedConfig.buildEs5);
setBooleanConfig(validatedConfig, 'profile', 'profile', validatedConfig.devMode);
setBooleanConfig(validatedConfig, 'writeLog', 'log', false);
setBooleanConfig(validatedConfig, 'buildAppCore', null, true);
setBooleanConfig(validatedConfig, 'autoprefixCss', null, validatedConfig.buildEs5);
setBooleanConfig(validatedConfig, 'validateTypes', null, !validatedConfig._isTesting);
setBooleanConfig(validatedConfig, 'allowInlineScripts', null, true);
setBooleanConfig(validatedConfig, 'suppressReservedPublicNameWarnings', null, false);
if (!isString(validatedConfig.taskQueue)) {
validatedConfig.taskQueue = 'async';
}
// hash file names
if (!isBoolean(validatedConfig.hashFileNames)) {
validatedConfig.hashFileNames = !validatedConfig.devMode;
}
if (!isNumber(validatedConfig.hashedFileNameLength)) {
validatedConfig.hashedFileNameLength = DEFAULT_HASHED_FILENAME_LENGTH;
}
if (validatedConfig.hashedFileNameLength < MIN_HASHED_FILENAME_LENGTH) {
const err = buildError(diagnostics);
err.messageText = `validatedConfig.hashedFileNameLength must be at least ${MIN_HASHED_FILENAME_LENGTH} characters`;
}
if (validatedConfig.hashedFileNameLength > MAX_HASHED_FILENAME_LENGTH) {
const err = buildError(diagnostics);
err.messageText = `validatedConfig.hashedFileNameLength cannot be more than ${MAX_HASHED_FILENAME_LENGTH} characters`;
}
if (!validatedConfig.env) {
validatedConfig.env = {};
}
// outputTargets
validateOutputTargets(validatedConfig, diagnostics);
// plugins
validatePlugins(validatedConfig, diagnostics);
// dev server
validatedConfig.devServer = validateDevServer(validatedConfig, diagnostics);
// testing
validateTesting(validatedConfig, diagnostics);
// bundles
if (Array.isArray(validatedConfig.bundles)) {
validatedConfig.bundles = sortBy(validatedConfig.bundles, (a: ConfigBundle) => a.components.length);
} else {
validatedConfig.bundles = [];
}
// exclude components (tag list)
if (!Array.isArray(validatedConfig.excludeComponents)) {
validatedConfig.excludeComponents = [];
}
// validate how many workers we can use
validateWorkers(validatedConfig);
// default devInspector to whatever devMode is
setBooleanConfig(validatedConfig, 'devInspector', null, validatedConfig.devMode);
if (!validatedConfig._isTesting) {
validateDistNamespace(validatedConfig, diagnostics);
}
setBooleanConfig(validatedConfig, 'enableCache', 'cache', true);
if (!Array.isArray(validatedConfig.watchIgnoredRegex) && validatedConfig.watchIgnoredRegex != null) {
validatedConfig.watchIgnoredRegex = [validatedConfig.watchIgnoredRegex];
}
validatedConfig.watchIgnoredRegex = ((validatedConfig.watchIgnoredRegex as RegExp[]) || []).reduce((arr, reg) => {
if (reg instanceof RegExp) {
arr.push(reg);
}
return arr;
}, [] as RegExp[]);
// TODO(STENCIL-1107): Remove this check. It'll be unneeded (and raise a compilation error when we build Stencil) once
// this property is removed.
if (validatedConfig.nodeResolve?.customResolveOptions) {
const warn = buildWarn(diagnostics);
// this message is particularly long - let the underlying logger implementation take responsibility for breaking it
// up to fit in a terminal window
warn.messageText = `nodeResolve.customResolveOptions is a deprecated option in a Stencil Configuration file. If you need this option, please open a new issue in the Stencil repository (https://github.com/stenciljs/core/issues/new/choose)`;
}
CACHED_VALIDATED_CONFIG = validatedConfig;
return {
config: validatedConfig,
diagnostics,
};
};
================================================
FILE: src/compiler/config/validate-copy.ts
================================================
import { unique } from '@utils';
import type * as d from '../../declarations';
/**
* Validate a series of {@link d.CopyTask}s
* @param copy the copy tasks to validate, or a boolean to specify if copy tasks are enabled
* @param defaultCopy default copy tasks to add to the returned validated list if not present in the first argument
* @returns the validated copy tasks
*/
export const validateCopy = (
copy: d.CopyTask[] | boolean | null | undefined,
defaultCopy: d.CopyTask[] = [],
): d.CopyTask[] => {
if (copy === null || copy === false) {
return [];
}
if (!Array.isArray(copy)) {
copy = [];
}
copy = copy.slice();
for (const task of defaultCopy) {
if (copy.every((t) => t.src !== task.src)) {
copy.push(task);
}
}
return unique(copy, (task) => `${task.src}:${task.dest}:${task.keepDirStructure}`);
};
================================================
FILE: src/compiler/config/validate-dev-server.ts
================================================
import { buildError, isBoolean, isNumber, isOutputTargetWww, isString, join, normalizePath } from '@utils';
import { isAbsolute } from 'path';
import type * as d from '../../declarations';
export const validateDevServer = (config: d.ValidatedConfig, diagnostics: d.Diagnostic[]): d.DevServerConfig => {
if ((config.devServer === null || (config.devServer as any)) === false) {
return {};
}
const { flags } = config;
const devServer = { ...config.devServer };
if (flags.address && isString(flags.address)) {
devServer.address = flags.address;
} else if (!isString(devServer.address)) {
devServer.address = '0.0.0.0';
}
// default to http for local dev
let addressProtocol: 'http' | 'https' = 'http';
if (devServer.address.toLowerCase().startsWith('http://')) {
devServer.address = devServer.address.substring(7);
addressProtocol = 'http';
} else if (devServer.address.toLowerCase().startsWith('https://')) {
devServer.address = devServer.address.substring(8);
addressProtocol = 'https';
}
devServer.address = devServer.address.split('/')[0];
// Validate "ping" route option
if (devServer.pingRoute !== null) {
let pingRoute = isString(devServer.pingRoute) ? devServer.pingRoute : '/ping';
if (!pingRoute.startsWith('/')) {
pingRoute = `/${pingRoute}`;
}
devServer.pingRoute = pingRoute;
}
// split on `:` to get the domain and the (possibly present) port
// separately. we've already sliced off the protocol (if present) above
// so we can safely split on `:` here.
const addressSplit = devServer.address.split(':');
const isLocalhost = addressSplit[0] === 'localhost' || !isNaN(addressSplit[0].split('.')[0] as any);
// if localhost we use 3333 as a default port
let addressPort: number | undefined = isLocalhost ? 3333 : undefined;
if (addressSplit.length > 1) {
if (!isNaN(addressSplit[1] as any)) {
devServer.address = addressSplit[0];
addressPort = parseInt(addressSplit[1], 10);
}
}
if (isNumber(flags.port)) {
devServer.port = flags.port;
} else if (devServer.port !== null && !isNumber(devServer.port)) {
if (isNumber(addressPort)) {
devServer.port = addressPort;
}
}
if (devServer.reloadStrategy === undefined) {
devServer.reloadStrategy = 'hmr';
} else if (
devServer.reloadStrategy !== 'hmr' &&
devServer.reloadStrategy !== 'pageReload' &&
devServer.reloadStrategy !== null
) {
const err = buildError(diagnostics);
err.messageText = `Invalid devServer reloadStrategy "${devServer.reloadStrategy}". Valid configs include "hmr", "pageReload" and null.`;
}
if (!isBoolean(devServer.gzip)) {
devServer.gzip = true;
}
if (!isBoolean(devServer.openBrowser)) {
devServer.openBrowser = true;
}
if (!isBoolean(devServer.websocket)) {
devServer.websocket = true;
}
if (!isBoolean(devServer.strictPort)) {
devServer.strictPort = false;
}
if (flags.ssr) {
devServer.ssr = true;
} else {
devServer.ssr = !!devServer.ssr;
}
if (devServer.ssr) {
const wwwOutput = (config.outputTargets ?? []).find(isOutputTargetWww);
devServer.prerenderConfig = wwwOutput?.prerenderConfig;
}
if (isString(config.srcIndexHtml)) {
devServer.srcIndexHtml = normalizePath(config.srcIndexHtml);
}
if (devServer.protocol !== 'http' && devServer.protocol !== 'https') {
devServer.protocol = devServer.https ? 'https' : addressProtocol ? addressProtocol : 'http';
}
if (devServer.historyApiFallback !== null) {
if (Array.isArray(devServer.historyApiFallback) || typeof devServer.historyApiFallback !== 'object') {
devServer.historyApiFallback = {};
}
if (!isString(devServer.historyApiFallback.index)) {
devServer.historyApiFallback.index = 'index.html';
}
if (!isBoolean(devServer.historyApiFallback.disableDotRule)) {
devServer.historyApiFallback.disableDotRule = false;
}
}
if (flags.open === false) {
devServer.openBrowser = false;
} else if (flags.prerender && !config.watch) {
devServer.openBrowser = false;
}
let serveDir: string;
let basePath: string;
const wwwOutputTarget = (config.outputTargets ?? []).find(isOutputTargetWww);
if (wwwOutputTarget) {
const baseUrl = new URL(wwwOutputTarget.baseUrl ?? '', 'http://config.stenciljs.com');
basePath = baseUrl.pathname;
serveDir = wwwOutputTarget.appDir ?? '';
} else {
basePath = '';
serveDir = config.rootDir ?? '';
}
if (!isString(basePath) || basePath.trim() === '') {
basePath = `/`;
}
basePath = normalizePath(basePath);
if (!basePath.startsWith('/')) {
basePath = '/' + basePath;
}
if (!basePath.endsWith('/')) {
basePath += '/';
}
if (!isBoolean(devServer.logRequests)) {
devServer.logRequests = config.logLevel === 'debug';
}
if (!isString(devServer.root)) {
devServer.root = serveDir;
}
if (!isString(devServer.basePath)) {
devServer.basePath = basePath;
}
if (isString((devServer as any).baseUrl)) {
const err = buildError(diagnostics);
err.messageText = `devServer config "baseUrl" has been renamed to "basePath", and should not include a domain or protocol.`;
}
if (!isAbsolute(devServer.root)) {
devServer.root = join(config.rootDir as string, devServer.root);
}
devServer.root = normalizePath(devServer.root);
if (devServer.excludeHmr) {
if (!Array.isArray(devServer.excludeHmr)) {
const err = buildError(diagnostics);
err.messageText = `dev server excludeHmr must be an array of glob strings`;
}
} else {
devServer.excludeHmr = [];
}
if (!config.devMode || config.buildEs5) {
devServer.experimentalDevModules = false;
} else {
devServer.experimentalDevModules = !!devServer.experimentalDevModules;
}
return devServer;
};
================================================
FILE: src/compiler/config/validate-docs.ts
================================================
import * as d from '../../declarations';
import { UnvalidatedConfig } from '../../declarations';
import { isHexColor } from '../docs/readme/docs-util';
import { DEFAULT_TARGET_COMPONENT_STYLES } from './constants';
/**
* Validate the `.docs` property on the supplied config object and
* return a properly-validated value.
*
* @param config the configuration we're examining
* @param logger the logger that will be set on the config
* @returns a suitable/default value for the docs property
*/
export const validateDocs = (config: UnvalidatedConfig, logger: d.Logger): d.ValidatedConfig['docs'] => {
const { background: defaultBackground, textColor: defaultTextColor } = DEFAULT_TARGET_COMPONENT_STYLES;
let { background = defaultBackground, textColor = defaultTextColor } =
config.docs?.markdown?.targetComponent ?? DEFAULT_TARGET_COMPONENT_STYLES;
if (!isHexColor(background)) {
logger.warn(
`'${background}' is not a valid hex color. The default value for diagram backgrounds ('${defaultBackground}') will be used.`,
);
background = defaultBackground;
}
if (!isHexColor(textColor)) {
logger.warn(
`'${textColor}' is not a valid hex color. The default value for diagram text ('${defaultTextColor}') will be used.`,
);
textColor = defaultTextColor;
}
return {
markdown: {
targetComponent: {
background,
textColor,
},
},
};
};
================================================
FILE: src/compiler/config/validate-hydrated.ts
================================================
import { isString } from '@utils';
import { HydratedFlag, UnvalidatedConfig } from '../../declarations';
/**
* Validate the `.hydratedFlag` property on the supplied config object and
* return a properly-validated value.
*
* @param config the configuration we're examining
* @returns a suitable value for the hydratedFlag property
*/
export const validateHydrated = (config: UnvalidatedConfig): HydratedFlag | null => {
/**
* If `config.hydratedFlag` is set to `null` that is an explicit signal that we
* should _not_ create a default configuration when validating and should instead
* just return `null`. It may also have been set to `false`; this is an invalid
* value as far as the type system is concerned, but users may ignore this.
*
* See {@link HydratedFlag} for more details.
*/
if (config.hydratedFlag === null || (config.hydratedFlag as unknown as boolean) === false) {
return null;
}
// Here we start building up a default config since `.hydratedFlag` wasn't set to
// `null` on the provided config.
const hydratedFlag: HydratedFlag = { ...(config.hydratedFlag ?? {}) };
if (!isString(hydratedFlag.name) || hydratedFlag.property === '') {
hydratedFlag.name = `hydrated`;
}
if (hydratedFlag.selector === 'attribute') {
hydratedFlag.selector = `attribute`;
} else {
hydratedFlag.selector = `class`;
}
if (!isString(hydratedFlag.property) || hydratedFlag.property === '') {
hydratedFlag.property = `visibility`;
}
if (!isString(hydratedFlag.initialValue) && hydratedFlag.initialValue !== null) {
hydratedFlag.initialValue = `hidden`;
}
if (!isString(hydratedFlag.hydratedValue) && hydratedFlag.initialValue !== null) {
hydratedFlag.hydratedValue = `inherit`;
}
return hydratedFlag;
};
================================================
FILE: src/compiler/config/validate-namespace.ts
================================================
import { buildError, dashToPascalCase, isOutputTargetDist, isString } from '@utils';
import type * as d from '../../declarations';
import { DEFAULT_NAMESPACE } from './constants';
/**
* Ensures that the `namespace` and `fsNamespace` properties on a project's
* Stencil config are valid strings. A valid namespace means:
* - at least 3 characters
* - cannot start with a number or dash
* - cannot end with a dash
* - must only contain alphanumeric, dash, and dollar sign characters
*
* If any conditions are not met, a diagnostic is added to the provided array.
*
* If a namespace is not provided, the default value is `App`.
*
* @param namespace The namespace to validate
* @param fsNamespace The fsNamespace to validate
* @param diagnostics The array of diagnostics to add to if the namespace is invalid
* @returns The validated namespace and fsNamespace
*/
export const validateNamespace = (
namespace: string | undefined,
fsNamespace: string | undefined,
diagnostics: d.Diagnostic[],
) => {
namespace = isString(namespace) ? namespace : DEFAULT_NAMESPACE;
namespace = namespace.trim();
const invalidNamespaceChars = namespace.replace(/(\w)|(\-)|(\$)/g, '');
if (invalidNamespaceChars !== '') {
const err = buildError(diagnostics);
err.messageText = `Namespace "${namespace}" contains invalid characters: ${invalidNamespaceChars}`;
}
if (namespace.length < 3) {
const err = buildError(diagnostics);
err.messageText = `Namespace "${namespace}" must be at least 3 characters`;
}
if (/^\d+$/.test(namespace.charAt(0))) {
const err = buildError(diagnostics);
err.messageText = `Namespace "${namespace}" cannot have a number for the first character`;
}
if (namespace.charAt(0) === '-') {
const err = buildError(diagnostics);
err.messageText = `Namespace "${namespace}" cannot have a dash for the first character`;
}
if (namespace.charAt(namespace.length - 1) === '-') {
const err = buildError(diagnostics);
err.messageText = `Namespace "${namespace}" cannot have a dash for the last character`;
}
// the file system namespace is the one
// used in filenames and seen in the url
if (!isString(fsNamespace)) {
fsNamespace = namespace.toLowerCase().trim();
}
if (namespace.includes('-')) {
// convert to PascalCase
namespace = dashToPascalCase(namespace);
}
return { namespace, fsNamespace };
};
export const validateDistNamespace = (config: d.UnvalidatedConfig, diagnostics: d.Diagnostic[]) => {
const hasDist = (config.outputTargets ?? []).some(isOutputTargetDist);
if (hasDist) {
if (!isString(config.namespace) || config.namespace.toLowerCase() === 'app') {
const err = buildError(diagnostics);
err.messageText = `When generating a distribution it is recommended to choose a unique namespace rather than the default setting "App". Please updated the "namespace" config property within the stencil config.`;
}
}
};
================================================
FILE: src/compiler/config/validate-paths.ts
================================================
import { join, normalizePath } from '@utils';
import { isAbsolute } from 'path';
import type * as d from '../../declarations';
/**
* The paths validated in this module. These fields can be incorporated into a
* {@link d.ValidatedConfig} object.
*/
interface ConfigPaths {
rootDir: string;
srcDir: string;
packageJsonFilePath: string;
cacheDir: string;
srcIndexHtml: string;
globalScript?: string;
globalStyle?: string;
buildLogFilePath?: string;
}
/**
* Do logical-level validation (as opposed to type-level validation)
* for various properties in the user-supplied config which represent
* filesystem paths.
*
* @param config a validated user-supplied configuration
* @returns an object holding the validated paths
*/
export const validatePaths = (config: d.Config): ConfigPaths => {
const rootDir = typeof config.rootDir !== 'string' ? '/' : config.rootDir;
let srcDir = typeof config.srcDir !== 'string' ? DEFAULT_SRC_DIR : config.srcDir;
if (!isAbsolute(srcDir)) {
srcDir = join(rootDir, srcDir);
}
let cacheDir = typeof config.cacheDir !== 'string' ? DEFAULT_CACHE_DIR : config.cacheDir;
if (!isAbsolute(cacheDir)) {
cacheDir = join(rootDir, cacheDir);
} else {
cacheDir = normalizePath(cacheDir);
}
let srcIndexHtml = typeof config.srcIndexHtml !== 'string' ? join(srcDir, DEFAULT_INDEX_HTML) : config.srcIndexHtml;
if (!isAbsolute(srcIndexHtml)) {
srcIndexHtml = join(rootDir, srcIndexHtml);
}
const packageJsonFilePath = join(rootDir, 'package.json');
const validatedPaths: ConfigPaths = {
rootDir,
srcDir,
cacheDir,
srcIndexHtml,
packageJsonFilePath,
};
if (typeof config.globalScript === 'string' && !isAbsolute(config.globalScript)) {
validatedPaths.globalScript = join(rootDir, config.globalScript);
}
if (typeof config.globalStyle === 'string' && !isAbsolute(config.globalStyle)) {
validatedPaths.globalStyle = join(rootDir, config.globalStyle);
}
if (config.writeLog) {
validatedPaths.buildLogFilePath =
typeof config.buildLogFilePath === 'string' ? config.buildLogFilePath : DEFAULT_BUILD_LOG_FILE_NAME;
if (!isAbsolute(validatedPaths.buildLogFilePath)) {
validatedPaths.buildLogFilePath = join(rootDir, config.buildLogFilePath);
}
}
return validatedPaths;
};
const DEFAULT_BUILD_LOG_FILE_NAME = 'stencil-build.log';
const DEFAULT_CACHE_DIR = '.stencil';
const DEFAULT_INDEX_HTML = 'index.html';
const DEFAULT_SRC_DIR = 'src';
================================================
FILE: src/compiler/config/validate-plugins.ts
================================================
import { buildWarn } from '@utils';
import type * as d from '../../declarations';
export const validatePlugins = (config: d.UnvalidatedConfig, diagnostics: d.Diagnostic[]) => {
const userPlugins = config.plugins;
if (!config.rollupPlugins) {
config.rollupPlugins = {};
}
if (!Array.isArray(userPlugins)) {
config.plugins = [];
return;
}
const rollupPlugins = userPlugins.filter((plugin) => {
return !!(plugin && typeof plugin === 'object' && !plugin.pluginType);
});
const hasResolveNode = rollupPlugins.some((p) => p.name === 'node-resolve');
const hasCommonjs = rollupPlugins.some((p) => p.name === 'commonjs');
if (hasCommonjs) {
const warn = buildWarn(diagnostics);
warn.messageText = `Stencil already uses "@rollup/plugin-commonjs", please remove it from your "stencil.config.ts" plugins.
You can configure the commonjs settings using the "commonjs" property in "stencil.config.ts`;
}
if (hasResolveNode) {
const warn = buildWarn(diagnostics);
warn.messageText = `Stencil already uses "@rollup/plugin-commonjs", please remove it from your "stencil.config.ts" plugins.
You can configure the commonjs settings using the "commonjs" property in "stencil.config.ts`;
}
config.rollupPlugins.before = [
...(config.rollupPlugins.before || []),
...rollupPlugins.filter(({ name }) => name !== 'node-resolve' && name !== 'commonjs'),
];
config.plugins = userPlugins.filter((plugin) => {
return !!(plugin && typeof plugin === 'object' && plugin.pluginType);
});
};
================================================
FILE: src/compiler/config/validate-prerender.ts
================================================
import { buildError, isString, join, normalizePath } from '@utils';
import { isAbsolute } from 'path';
import type * as d from '../../declarations';
export const validatePrerender = (
config: d.ValidatedConfig,
diagnostics: d.Diagnostic[],
outputTarget: d.OutputTargetWww,
) => {
if (!config.flags.ssr && !config.flags.prerender && config.flags.task !== 'prerender') {
return;
}
outputTarget.baseUrl = normalizePath(outputTarget.baseUrl);
if (!outputTarget.baseUrl.startsWith('http://') && !outputTarget.baseUrl.startsWith('https://')) {
const err = buildError(diagnostics);
err.messageText = `When prerendering, the "baseUrl" output target config must be a full URL and start with either "http://" or "https://". The config can be updated in the "www" output target within the stencil config.`;
}
try {
new URL(outputTarget.baseUrl);
} catch (e) {
const err = buildError(diagnostics);
err.messageText = `invalid "baseUrl": ${e}`;
}
if (!outputTarget.baseUrl.endsWith('/')) {
outputTarget.baseUrl += '/';
}
if (isString(outputTarget.prerenderConfig)) {
if (!isAbsolute(outputTarget.prerenderConfig)) {
outputTarget.prerenderConfig = join(config.rootDir, outputTarget.prerenderConfig);
}
}
};
================================================
FILE: src/compiler/config/validate-rollup-config.ts
================================================
import { isObject, pluck } from '@utils';
import type * as d from '../../declarations';
/**
* Ensure that a valid baseline rollup configuration is set on the validated
* config.
*
* If a config is present this will return a new config based on the user
* supplied one.
*
* If no config is present, this will return a default config.
*
* @param config a validated user-supplied configuration object
* @returns a validated rollup configuration
*/
export const validateRollupConfig = (config: d.Config): d.RollupConfig => {
let cleanRollupConfig = { ...DEFAULT_ROLLUP_CONFIG };
const rollupConfig = config.rollupConfig;
if (!rollupConfig || !isObject(rollupConfig)) {
return cleanRollupConfig;
}
if (rollupConfig.inputOptions && isObject(rollupConfig.inputOptions)) {
cleanRollupConfig = {
...cleanRollupConfig,
inputOptions: pluck(rollupConfig.inputOptions, [
'context',
'moduleContext',
'treeshake',
'external',
'maxParallelFileOps',
]),
};
}
if (rollupConfig.outputOptions && isObject(rollupConfig.outputOptions)) {
cleanRollupConfig = {
...cleanRollupConfig,
outputOptions: pluck(rollupConfig.outputOptions, ['globals']),
};
}
return cleanRollupConfig;
};
const DEFAULT_ROLLUP_CONFIG: d.RollupConfig = {
inputOptions: {},
outputOptions: {},
};
================================================
FILE: src/compiler/config/validate-service-worker.ts
================================================
import { isString, join } from '@utils';
import { isAbsolute } from 'path';
import type * as d from '../../declarations';
/**
* Validate that a service worker configuration is valid, if it is present and
* accounted for.
*
* Note that our service worker configuration / support is based on
* Workbox, a package for automatically generating Service Workers to cache
* assets on the client. More here: https://developer.chrome.com/docs/workbox/
*
* This function first checks that the service worker config set on the
* supplied `OutputTarget` is not empty and that we are not currently in
* development mode. In those cases it will early return.
*
* If we do find a service worker configuration we do some validation to ensure
* that things are set up correctly.
*
* @param config the current, validated configuration
* @param outputTarget the `www` outputTarget whose service worker
* configuration we want to validate. **Note**: the `.serviceWorker` object
* _will be mutated_ if it is present.
*/
export const validateServiceWorker = (config: d.ValidatedConfig, outputTarget: d.OutputTargetWww): void => {
if (outputTarget.serviceWorker === false) {
return;
}
if (config.devMode && !config.flags.serviceWorker) {
outputTarget.serviceWorker = null;
return;
}
if (outputTarget.serviceWorker === null) {
outputTarget.serviceWorker = null;
return;
}
if (!outputTarget.serviceWorker && config.devMode) {
outputTarget.serviceWorker = null;
return;
}
const globDirectory =
typeof outputTarget.serviceWorker?.globDirectory === 'string'
? outputTarget.serviceWorker.globDirectory
: outputTarget.appDir;
outputTarget.serviceWorker = {
...outputTarget.serviceWorker,
globDirectory,
swDest: isString(outputTarget.serviceWorker?.swDest)
? outputTarget.serviceWorker.swDest
: join(outputTarget.appDir ?? '', DEFAULT_FILENAME),
};
if (!Array.isArray(outputTarget.serviceWorker.globPatterns)) {
if (typeof outputTarget.serviceWorker.globPatterns === 'string') {
outputTarget.serviceWorker.globPatterns = [outputTarget.serviceWorker.globPatterns];
} else if (typeof outputTarget.serviceWorker.globPatterns !== 'string') {
outputTarget.serviceWorker.globPatterns = DEFAULT_GLOB_PATTERNS.slice();
}
}
if (typeof outputTarget.serviceWorker.globIgnores === 'string') {
outputTarget.serviceWorker.globIgnores = [outputTarget.serviceWorker.globIgnores];
}
outputTarget.serviceWorker.globIgnores = outputTarget.serviceWorker.globIgnores || [];
addGlobIgnores(config, outputTarget.serviceWorker.globIgnores);
outputTarget.serviceWorker.dontCacheBustURLsMatching = /p-\w{8}/;
if (isString(outputTarget.serviceWorker.swSrc) && !isAbsolute(outputTarget.serviceWorker.swSrc)) {
outputTarget.serviceWorker.swSrc = join(config.rootDir, outputTarget.serviceWorker.swSrc);
}
if (isString(outputTarget.serviceWorker.swDest) && !isAbsolute(outputTarget.serviceWorker.swDest)) {
outputTarget.serviceWorker.swDest = join(outputTarget.appDir ?? '', outputTarget.serviceWorker.swDest);
}
};
/**
* Add file glob patterns to the `globIgnores` for files we don't want to cache
* with the service worker.
*
* @param config the current, validated configuration
* @param globIgnores list of file ignore patterns. **Note**: will be mutated.
*/
const addGlobIgnores = (config: d.ValidatedConfig, globIgnores: string[]) => {
globIgnores.push(
`**/host.config.json`, // the filename of the host configuration
`**/*.system.entry.js`,
`**/*.system.js`,
`**/${config.fsNamespace}.js`,
`**/${config.fsNamespace}.esm.js`,
`**/${config.fsNamespace}.css`,
);
};
const DEFAULT_GLOB_PATTERNS = ['*.html', '**/*.{js,css,json}'];
const DEFAULT_FILENAME = 'sw.js';
================================================
FILE: src/compiler/config/validate-testing.ts
================================================
import { buildError, isOutputTargetDist, isOutputTargetWww, isString, join, normalizePath } from '@utils';
import { basename, dirname, isAbsolute } from 'path';
import type * as d from '../../declarations';
import { isLocalModule } from '../sys/resolve/resolve-utils';
export const validateTesting = (config: d.ValidatedConfig, diagnostics: d.Diagnostic[]) => {
const testing = (config.testing = Object.assign({}, config.testing || {}));
if (!config.flags.e2e && !config.flags.spec) {
return;
}
let configPathDir = config.configPath!;
if (isString(configPathDir)) {
if (basename(configPathDir).includes('.')) {
configPathDir = dirname(configPathDir);
}
} else {
configPathDir = config.rootDir!;
}
if (typeof config.flags.headless === 'boolean' || config.flags.headless === 'shell') {
testing.browserHeadless = config.flags.headless;
} else if (typeof testing.browserHeadless !== 'boolean' && testing.browserHeadless !== 'shell') {
testing.browserHeadless = 'shell';
}
/**
* Using the deprecated `browserHeadless: true` flag causes Chrome to crash when running tests.
* Ensure users don't run into this by throwing a deliberate error.
*/
if (typeof testing.browserHeadless === 'boolean' && testing.browserHeadless) {
throw new Error(`Setting "browserHeadless" config to \`true\` is not supported anymore, please set it to "shell"!`);
}
if (!testing.browserWaitUntil) {
testing.browserWaitUntil = 'load';
}
/**
* ensure we always test on stable Chrome
*/
if (!isString(testing.browserChannel)) {
testing.browserChannel = 'chrome';
}
testing.browserArgs = testing.browserArgs || [];
addTestingConfigOption(testing.browserArgs, '--font-render-hinting=medium');
addTestingConfigOption(testing.browserArgs, '--incognito');
if (config.flags.ci || process.env.CI) {
addTestingConfigOption(testing.browserArgs, '--no-sandbox');
addTestingConfigOption(testing.browserArgs, '--disable-setuid-sandbox');
addTestingConfigOption(testing.browserArgs, '--disable-dev-shm-usage');
testing.browserHeadless = 'shell';
} else if (config.flags.devtools || testing.browserDevtools) {
testing.browserDevtools = true;
testing.browserHeadless = false;
}
if (typeof testing.rootDir === 'string') {
if (!isAbsolute(testing.rootDir)) {
testing.rootDir = join(config.rootDir!, testing.rootDir);
}
} else {
testing.rootDir = config.rootDir;
}
if (typeof config.flags.screenshotConnector === 'string') {
testing.screenshotConnector = config.flags.screenshotConnector;
}
if (typeof testing.screenshotConnector === 'string') {
if (!isAbsolute(testing.screenshotConnector)) {
testing.screenshotConnector = join(config.rootDir!, testing.screenshotConnector);
} else {
testing.screenshotConnector = normalizePath(testing.screenshotConnector);
}
} else {
testing.screenshotConnector = join(
config.sys!.getCompilerExecutingPath(),
'..',
'..',
'screenshot',
'local-connector.js',
);
}
/**
* We only allow numbers or null for the screenshotTimeout, so if we detect anything
* else, we set it to null.
*/
if (typeof testing.screenshotTimeout != 'number') {
testing.screenshotTimeout = null;
}
if (!Array.isArray(testing.testPathIgnorePatterns)) {
testing.testPathIgnorePatterns = DEFAULT_IGNORE_PATTERNS.map((ignorePattern) => {
return join(testing.rootDir!, ignorePattern);
});
(config.outputTargets ?? [])
.filter(
(o): o is d.OutputTargetWww | d.OutputTargetDist => (isOutputTargetDist(o) || isOutputTargetWww(o)) && !!o.dir,
)
.forEach((outputTarget) => {
testing.testPathIgnorePatterns?.push(outputTarget.dir!);
});
}
if (typeof testing.preset !== 'string') {
testing.preset = join(config.sys!.getCompilerExecutingPath(), '..', '..', 'testing');
} else if (!isAbsolute(testing.preset)) {
testing.preset = join(configPathDir, testing.preset);
}
if (!Array.isArray(testing.setupFilesAfterEnv)) {
testing.setupFilesAfterEnv = [];
}
testing.setupFilesAfterEnv.unshift(
join(config.sys!.getCompilerExecutingPath(), '..', '..', 'testing', 'jest-setuptestframework.js'),
);
if (isString(testing.testEnvironment)) {
if (!isAbsolute(testing.testEnvironment) && isLocalModule(testing.testEnvironment)) {
testing.testEnvironment = join(configPathDir, testing.testEnvironment);
}
}
if (typeof testing.allowableMismatchedPixels === 'number') {
if (testing.allowableMismatchedPixels < 0) {
const err = buildError(diagnostics);
err.messageText = `allowableMismatchedPixels must be a value that is 0 or greater`;
}
} else {
testing.allowableMismatchedPixels = DEFAULT_ALLOWABLE_MISMATCHED_PIXELS;
}
if (typeof testing.allowableMismatchedRatio === 'number') {
if (testing.allowableMismatchedRatio < 0 || testing.allowableMismatchedRatio > 1) {
const err = buildError(diagnostics);
err.messageText = `allowableMismatchedRatio must be a value ranging from 0 to 1`;
}
}
if (typeof testing.pixelmatchThreshold === 'number') {
if (testing.pixelmatchThreshold < 0 || testing.pixelmatchThreshold > 1) {
const err = buildError(diagnostics);
err.messageText = `pixelmatchThreshold must be a value ranging from 0 to 1`;
}
} else {
testing.pixelmatchThreshold = DEFAULT_PIXEL_MATCH_THRESHOLD;
}
if (testing.testRegex === undefined) {
/**
* The test regex covers cases of:
* - files under a `__tests__` directory
* - the case where a test file has a name such as `test.ts`, `spec.ts` or `e2e.ts`.
* - these files can use any of the following file extensions: .ts, .tsx, .js, .jsx.
* - this regex only handles the entire path of a file, e.g. `/some/path/e2e.ts`
* - the case where a test file ends with `.test.ts`, `.spec.ts`, or `.e2e.ts`.
* - these files can use any of the following file extensions: .ts, .tsx, .js, .jsx.
* - this regex case shall match file names such as `my-cmp.spec.ts`, `test.spec.ts`
* - this regex case shall not match file names such as `attest.ts`, `bespec.ts`
*/
testing.testRegex = ['(/__tests__/.*|(\\.|/)(test|spec|e2e))\\.[jt]sx?$'];
} else if (typeof testing.testRegex === 'string') {
testing.testRegex = [testing.testRegex];
}
if (Array.isArray(testing.testMatch)) {
delete testing.testRegex;
} else if (typeof testing.testRegex === 'string') {
delete testing.testMatch;
}
if (typeof testing.runner !== 'string') {
testing.runner = join(config.sys!.getCompilerExecutingPath(), '..', '..', 'testing', 'jest-runner.js');
}
if (typeof testing.waitBeforeScreenshot === 'number') {
if (testing.waitBeforeScreenshot < 0) {
const err = buildError(diagnostics);
err.messageText = `waitBeforeScreenshot must be a value that is 0 or greater`;
}
} else {
testing.waitBeforeScreenshot = 10;
}
if (!Array.isArray(testing.emulate) || testing.emulate.length === 0) {
testing.emulate = [
{
userAgent: 'default',
viewport: {
width: 600,
height: 600,
deviceScaleFactor: 1,
isMobile: false,
hasTouch: false,
isLandscape: false,
},
},
];
}
};
const addTestingConfigOption = (setArray: string[], option: string) => {
if (!setArray.includes(option)) {
setArray.push(option);
}
};
const DEFAULT_ALLOWABLE_MISMATCHED_PIXELS = 100;
const DEFAULT_PIXEL_MATCH_THRESHOLD = 0.1;
const DEFAULT_IGNORE_PATTERNS = ['.vscode', '.stencil', 'node_modules'];
================================================
FILE: src/compiler/config/validate-workers.ts
================================================
import type * as d from '../../declarations';
export const validateWorkers = (config: d.ValidatedConfig) => {
if (typeof config.maxConcurrentWorkers !== 'number') {
config.maxConcurrentWorkers = 8;
}
if (typeof config.flags.maxWorkers === 'number') {
config.maxConcurrentWorkers = config.flags.maxWorkers;
} else if (config.flags.ci) {
config.maxConcurrentWorkers = 4;
}
config.maxConcurrentWorkers = Math.max(Math.min(config.maxConcurrentWorkers, 16), 0);
if (config.devServer) {
config.devServer.worker = config.maxConcurrentWorkers > 0;
}
};
================================================
FILE: src/compiler/docs/cem/index.ts
================================================
import { dashToPascalCase, isOutputTargetDocsCustomElementsManifest } from '@utils';
import type * as d from '../../../declarations';
/**
* Generate Custom Elements Manifest (custom-elements.json) output
* conforming to the Custom Elements Manifest specification.
* @see https://github.com/webcomponents/custom-elements-manifest
*
* @param compilerCtx the current compiler context
* @param docsData the generated docs data from Stencil components
* @param outputTargets the output targets configured for the build
*/
export const generateCustomElementsManifestDocs = async (
compilerCtx: d.CompilerCtx,
docsData: d.JsonDocs,
outputTargets: d.OutputTarget[],
): Promise => {
const cemOutputTargets = outputTargets.filter(isOutputTargetDocsCustomElementsManifest);
if (cemOutputTargets.length === 0) {
return;
}
const manifest = generateManifest(docsData);
const jsonContent = JSON.stringify(manifest, null, 2);
await Promise.all(cemOutputTargets.map((outputTarget) => compilerCtx.fs.writeFile(outputTarget.file!, jsonContent)));
};
/**
* Generate the Custom Elements Manifest from Stencil docs data
* @param docsData the generated docs data
* @returns the Custom Elements Manifest object
*/
const generateManifest = (docsData: d.JsonDocs): CustomElementsManifest => {
// Group components by their source file path
const componentsByFile = new Map();
for (const component of docsData.components) {
const filePath = component.filePath;
if (!componentsByFile.has(filePath)) {
componentsByFile.set(filePath, []);
}
componentsByFile.get(filePath)!.push(component);
}
const modules: JavaScriptModule[] = [];
for (const [filePath, components] of componentsByFile) {
const declarations: CustomElementDeclaration[] = components.map((component) => componentToDeclaration(component));
const exports: (JavaScriptExport | CustomElementExport)[] = components.flatMap((component) => {
const className = dashToPascalCase(component.tag);
return [
{
kind: 'js' as const,
name: className,
declaration: {
name: className,
},
},
{
kind: 'custom-element-definition' as const,
name: component.tag,
declaration: {
name: className,
},
},
];
});
modules.push({
kind: 'javascript-module',
path: filePath,
declarations,
exports,
});
}
return {
schemaVersion: '2.1.0',
modules,
};
};
/**
* Convert Stencil's ComponentCompilerTypeReferences to CEM TypeReference array
* @param references Stencil's type references map
* @returns CEM TypeReference array
*/
const convertTypeReferences = (references?: d.ComponentCompilerTypeReferences): TypeReference[] | undefined => {
if (!references || Object.keys(references).length === 0) {
return undefined;
}
return Object.entries(references).map(([name, ref]) => ({
name,
// Global types (like HTMLElement, Array) get 'global:' package
...(ref.location === 'global' && { package: 'global:' }),
// Imported types get their module path
...(ref.location === 'import' && ref.path && { module: ref.path }),
// Local types don't need package or module (they're in the same module)
}));
};
/**
* Create a CEM Type object from a type string and optional references
* @param text the type string
* @param references Stencil's type references map
* @returns CEM Type object
*/
const createType = (text: string, references?: d.ComponentCompilerTypeReferences): Type => {
const typeRefs = convertTypeReferences(references);
return {
text,
...(typeRefs && { references: typeRefs }),
};
};
/**
* Convert a Stencil component to a Custom Element Declaration
* @param component the Stencil component docs data
* @returns the Custom Element Declaration
*/
const componentToDeclaration = (component: d.JsonDocsComponent): CustomElementDeclaration => {
const className = dashToPascalCase(component.tag);
const attributes: Attribute[] = component.props
.filter((prop) => prop.attr !== undefined)
.map((prop) => ({
name: prop.attr!,
...(prop.docs && { description: prop.docs }),
...(prop.type && { type: createType(prop.type, prop.complexType?.references) }),
...(prop.default !== undefined && { default: prop.default }),
fieldName: prop.name,
...(prop.deprecation !== undefined && { deprecated: prop.deprecation || true }),
}));
const members: (CustomElementField | ClassMethod)[] = [
// Fields (properties)
...component.props.map(
(prop): CustomElementField => ({
kind: 'field',
name: prop.name,
...(prop.docs && { description: prop.docs }),
...(prop.type && { type: createType(prop.type, prop.complexType?.references) }),
...(prop.default !== undefined && { default: prop.default }),
...(prop.deprecation !== undefined && { deprecated: prop.deprecation || true }),
...(!prop.mutable && { readonly: true }),
...(prop.attr && { attribute: prop.attr }),
...(prop.reflectToAttr && { reflects: true }),
}),
),
// Methods
...component.methods.map(
(method): ClassMethod => ({
kind: 'method',
name: method.name,
...(method.docs && { description: method.docs }),
...(method.deprecation !== undefined && { deprecated: method.deprecation || true }),
...(method.parameters &&
method.parameters.length > 0 && {
parameters: method.parameters.map((param) => ({
name: param.name,
...(param.docs && { description: param.docs }),
...(param.type && { type: createType(param.type, method.complexType?.references) }),
})),
}),
...(method.returns && {
return: {
...(method.returns.type && { type: createType(method.returns.type, method.complexType?.references) }),
...(method.returns.docs && { description: method.returns.docs }),
},
}),
}),
),
];
const events: Event[] = component.events.map((event) => ({
name: event.event,
...(event.docs && { description: event.docs }),
type: createType(event.detail ? `CustomEvent<${event.detail}>` : 'CustomEvent', event.complexType?.references),
...(event.deprecation !== undefined && { deprecated: event.deprecation || true }),
}));
const slots: Slot[] = component.slots.map((slot) => ({
name: slot.name,
...(slot.docs && { description: slot.docs }),
}));
const cssParts: CssPart[] = component.parts.map((part) => ({
name: part.name,
...(part.docs && { description: part.docs }),
}));
const cssProperties: CssCustomProperty[] = component.styles
.filter((style) => style.annotation === 'prop')
.map((style) => ({
name: style.name,
...(style.docs && { description: style.docs }),
}));
// Generate demos from usage examples
const demos: Demo[] = Object.entries(component.usage || {}).map(([name, content]) => ({
// Create relative URL from usagesDir + filename
url: component.usagesDir ? `${component.usagesDir}/${name}.md` : `${name}.md`,
...(content && { description: content }),
}));
return {
kind: 'class',
customElement: true,
tagName: component.tag,
name: className,
...(component.docs && { description: component.docs }),
...(component.deprecation !== undefined && { deprecated: component.deprecation || true }),
...(attributes.length > 0 && { attributes }),
...(members.length > 0 && { members }),
...(events.length > 0 && { events }),
...(slots.length > 0 && { slots }),
...(cssParts.length > 0 && { cssParts }),
...(cssProperties.length > 0 && { cssProperties }),
...(component.customStates.length > 0 && {
customStates: component.customStates.map((state) => ({
name: state.name,
initialValue: state.initialValue,
...(state.docs && { description: state.docs }),
})),
}),
...(demos.length > 0 && { demos }),
};
};
// Custom Elements Manifest Types
// Based on https://github.com/webcomponents/custom-elements-manifest/blob/main/schema.d.ts
interface CustomElementsManifest {
schemaVersion: string;
modules: JavaScriptModule[];
}
interface JavaScriptModule {
kind: 'javascript-module';
path: string;
declarations?: CustomElementDeclaration[];
exports?: (JavaScriptExport | CustomElementExport)[];
}
interface JavaScriptExport {
kind: 'js';
name: string;
declaration: Reference;
}
interface CustomElementExport {
kind: 'custom-element-definition';
name: string;
declaration: Reference;
}
interface Reference {
name: string;
package?: string;
module?: string;
}
interface CustomElementDeclaration {
kind: 'class';
customElement: true;
tagName: string;
name: string;
description?: string;
deprecated?: boolean | string;
attributes?: Attribute[];
members?: (CustomElementField | ClassMethod)[];
events?: Event[];
slots?: Slot[];
cssParts?: CssPart[];
cssProperties?: CssCustomProperty[];
customStates?: CustomState[];
demos?: Demo[];
}
interface Demo {
url: string;
description?: string;
}
interface Attribute {
name: string;
description?: string;
type?: Type;
default?: string;
fieldName?: string;
deprecated?: boolean | string;
}
interface Type {
text: string;
references?: TypeReference[];
}
interface TypeReference {
name: string;
package?: string;
module?: string;
}
interface CustomElementField {
kind: 'field';
name: string;
description?: string;
type?: Type;
default?: string;
deprecated?: boolean | string;
readonly?: boolean;
attribute?: string;
reflects?: boolean;
}
interface ClassMethod {
kind: 'method';
name: string;
description?: string;
deprecated?: boolean | string;
parameters?: Parameter[];
return?: {
type?: Type;
description?: string;
};
}
interface Parameter {
name: string;
description?: string;
type?: Type;
}
interface Event {
name: string;
description?: string;
type: Type;
deprecated?: boolean | string;
}
interface Slot {
name: string;
description?: string;
}
interface CssPart {
name: string;
description?: string;
}
/**
* Custom state that can be targeted with the CSS :state() pseudo-class.
* This is a custom extension to the CEM spec.
*/
interface CustomState {
name: string;
initialValue: boolean;
description?: string;
}
interface CssCustomProperty {
name: string;
description?: string;
}
================================================
FILE: src/compiler/docs/constants.ts
================================================
export const AUTO_GENERATE_COMMENT = ``;
export const NOTE = `*Built with [StencilJS](https://stenciljs.com/)*`;
================================================
FILE: src/compiler/docs/custom/index.ts
================================================
import { isOutputTargetDocsCustom } from '@utils';
import type * as d from '../../../declarations';
export const generateCustomDocs = async (
config: d.ValidatedConfig,
docsData: d.JsonDocs,
outputTargets: d.OutputTarget[],
) => {
const customOutputTargets = outputTargets.filter(isOutputTargetDocsCustom);
if (customOutputTargets.length === 0) {
return;
}
await Promise.all(
customOutputTargets.map(async (customOutput) => {
try {
await customOutput.generator(docsData, config);
} catch (e) {
config.logger.error(`uncaught custom docs error: ${e}`);
}
}),
);
};
================================================
FILE: src/compiler/docs/generate-doc-data.ts
================================================
import {
DEFAULT_STYLE_MODE,
flatOne,
isOutputTargetDocsJson,
join,
normalizePath,
relative,
sortBy,
unique,
} from '@utils';
import { basename, dirname } from 'path';
import type * as d from '../../declarations';
import { JsonDocsValue } from '../../declarations';
import { typescriptVersion, version } from '../../version';
import { getBuildTimestamp } from '../build/build-ctx';
import { addFileToLibrary, getTypeLibrary } from '../transformers/type-library';
import { AUTO_GENERATE_COMMENT } from './constants';
/**
* Generate metadata that will be used to generate any given documentation-related
* output target(s)
*
* @param config the configuration associated with the current Stencil task run
* @param compilerCtx the current compiler context
* @param buildCtx the build context for the current Stencil task run
* @returns the generated metadata
*/
export const generateDocData = async (
config: d.ValidatedConfig,
compilerCtx: d.CompilerCtx,
buildCtx: d.BuildCtx,
): Promise => {
const jsonOutputTargets = config.outputTargets.filter(isOutputTargetDocsJson);
const supplementalPublicTypes = findSupplementalPublicTypes(jsonOutputTargets);
if (supplementalPublicTypes !== '') {
// if supplementalPublicTypes is set then we want to add all the public
// types in that file to the type library so that output targets producing
// documentation can make use of that data later.
addFileToLibrary(config, supplementalPublicTypes);
}
const typeLibrary = getTypeLibrary();
return {
timestamp: getBuildTimestamp(),
compiler: {
name: '@stencil/core',
version,
typescriptVersion,
},
components: await getDocsComponents(config, compilerCtx, buildCtx),
typeLibrary,
};
};
/**
* If the `supplementalPublicTypes` option is set on one output target, find that value and return it.
*
* @param outputTargets an array of docs-json output targets
* @returns the first value encountered for supplementalPublicTypes or an empty string
*/
function findSupplementalPublicTypes(outputTargets: d.OutputTargetDocsJson[]): string {
for (const docsJsonOT of outputTargets) {
if (docsJsonOT.supplementalPublicTypes) {
return docsJsonOT.supplementalPublicTypes;
}
}
return '';
}
/**
* Derive the metadata for each Stencil component
*
* @param config the configuration associated with the current Stencil task run
* @param compilerCtx the current compiler context
* @param buildCtx the build context for the current Stencil task run
* @returns the derived metadata
*/
const getDocsComponents = async (
config: d.ValidatedConfig,
compilerCtx: d.CompilerCtx,
buildCtx: d.BuildCtx,
): Promise => {
const results = await Promise.all(
buildCtx.moduleFiles.map(async (moduleFile) => {
const filePath = moduleFile.sourceFilePath;
const dirPath = normalizePath(dirname(filePath));
const readmePath = normalizePath(join(dirPath, 'readme.md'));
const usagesDir = normalizePath(join(dirPath, 'usage'));
const readme = await getUserReadmeContent(compilerCtx, readmePath);
const usage = await generateUsages(compilerCtx, usagesDir);
return moduleFile.cmps
.filter((cmp: d.ComponentCompilerMeta) => !cmp.internal && !cmp.isCollectionDependency)
.map((cmp: d.ComponentCompilerMeta) => ({
dirPath,
filePath: normalizePath(relative(config.rootDir, filePath), false),
fileName: basename(filePath),
readmePath,
usagesDir,
tag: cmp.tagName,
readme,
overview: cmp.docs.text,
usage,
docs: generateDocs(readme, cmp.docs),
docsTags: cmp.docs.tags,
encapsulation: getDocsEncapsulation(cmp),
dependents: cmp.directDependents,
dependencies: cmp.directDependencies,
dependencyGraph: buildDocsDepGraph(cmp, buildCtx.components),
deprecation: getDocsDeprecationText(cmp.docs.tags),
props: getDocsProperties(cmp),
methods: getDocsMethods(cmp.methods),
events: getDocsEvents(cmp.events),
styles: getDocsStyles(cmp),
slots: getDocsSlots(cmp.docs.tags),
parts: getDocsParts(cmp.htmlParts, cmp.docs.tags),
customStates: getDocsCustomStates(cmp),
listeners: getDocsListeners(cmp.listeners),
}));
}),
);
return sortBy(flatOne(results), (cmp) => cmp.tag);
};
const buildDocsDepGraph = (
cmp: d.ComponentCompilerMeta,
cmps: d.ComponentCompilerMeta[],
): d.JsonDocsDependencyGraph => {
const dependencies: d.JsonDocsDependencyGraph = {};
function walk(tagName: string): void {
if (!dependencies[tagName]) {
const cmp = cmps.find((c) => c.tagName === tagName);
const deps = cmp?.directDependencies;
if (deps?.length > 0) {
dependencies[tagName] = deps;
deps.forEach(walk);
}
}
}
walk(cmp.tagName);
// load dependents
cmp.directDependents.forEach((tagName) => {
if (dependencies[tagName] && !dependencies[tagName].includes(cmp.tagName)) {
dependencies[tagName].push(cmp.tagName);
} else {
dependencies[tagName] = [cmp.tagName];
}
});
return dependencies;
};
/**
* Determines the encapsulation string to use, based on the provided compiler metadata
* @param cmp the metadata for a single component
* @returns the encapsulation level, expressed as a string
*/
const getDocsEncapsulation = (cmp: d.ComponentCompilerMeta): 'shadow' | 'scoped' | 'none' => {
if (cmp.encapsulation === 'shadow') {
return 'shadow';
} else if (cmp.encapsulation === 'scoped') {
return 'scoped';
} else {
return 'none';
}
};
/**
* Generate a collection of JSDoc metadata for both real and virtual props
* @param cmpMeta the component metadata to derive JSDoc metadata from
* @returns the derived metadata
*/
const getDocsProperties = (cmpMeta: d.ComponentCompilerMeta): d.JsonDocsProp[] => {
return sortBy(
[...getRealProperties(cmpMeta.properties), ...getVirtualProperties(cmpMeta.virtualProperties)],
(p) => p.name,
);
};
/**
* Generate a collection of JSDoc metadata for props on a component
* @param properties the component's property metadata to derive JSDoc metadata from
* @returns the derived metadata
*/
const getRealProperties = (properties: d.ComponentCompilerProperty[]): d.JsonDocsProp[] => {
return properties
.filter((member) => !member.internal)
.map((member) => ({
name: member.name,
type: member.complexType.resolved,
complexType: member.complexType,
mutable: member.mutable,
attr: member.attribute,
reflectToAttr: !!member.reflect,
docs: member.docs.text,
docsTags: member.docs.tags,
default: member.defaultValue,
deprecation: getDocsDeprecationText(member.docs.tags),
values: parseTypeIntoValues(member.complexType.resolved),
optional: member.optional,
required: member.required,
getter: member.getter,
setter: member.setter,
}));
};
/**
* Generate a collection of JSDoc metadata for props on a component
* @param virtualProps the component's virtual property metadata to derive JSDoc metadata from
* @returns the derived metadata
*/
const getVirtualProperties = (virtualProps: d.ComponentCompilerVirtualProperty[]): d.JsonDocsProp[] => {
return virtualProps.map(
(member): d.JsonDocsProp => ({
name: member.name,
type: member.type,
mutable: false,
attr: member.name,
reflectToAttr: false,
docs: member.docs,
docsTags: [],
default: undefined,
deprecation: undefined,
values: parseTypeIntoValues(member.type),
optional: true,
required: false,
getter: undefined,
setter: undefined,
}),
);
};
const parseTypeIntoValues = (type: string): d.JsonDocsValue[] => {
if (typeof type === 'string') {
const unions = type.split('|').map((u) => u.trim());
const parsedUnions: JsonDocsValue[] = [];
unions.forEach((u) => {
if (u === 'true') {
parsedUnions.push({
value: 'true',
type: 'boolean',
});
return;
}
if (u === 'false') {
parsedUnions.push({
value: 'false',
type: 'boolean',
});
return;
}
if (!Number.isNaN(parseFloat(u))) {
// union is a number
parsedUnions.push({
value: u,
type: 'number',
});
return;
}
if (/^("|').+("|')$/gm.test(u)) {
// ionic is a string
parsedUnions.push({
value: u.slice(1, -1),
type: 'string',
});
return;
}
parsedUnions.push({
type: u,
});
});
return parsedUnions;
}
return [];
};
const getDocsMethods = (methods: d.ComponentCompilerMethod[]): d.JsonDocsMethod[] => {
return sortBy(methods, (member) => member.name)
.filter((member) => !member.internal)
.map(
(member) =>
{
name: member.name,
returns: {
type: member.complexType.return,
docs: member.docs.tags
.filter((t) => t.name === 'return' || t.name === 'returns')
.map((t) => t.text)
.join('\n'),
},
complexType: member.complexType,
signature: `${member.name}${member.complexType.signature}`,
parameters: member.complexType.parameters,
docs: member.docs.text,
docsTags: member.docs.tags,
deprecation: getDocsDeprecationText(member.docs.tags),
},
);
};
const getDocsEvents = (events: d.ComponentCompilerEvent[]): d.JsonDocsEvent[] => {
return sortBy(events, (eventMeta) => eventMeta.name.toLowerCase())
.filter((eventMeta) => !eventMeta.internal)
.map((eventMeta) => ({
event: eventMeta.name,
detail: eventMeta.complexType.resolved,
bubbles: eventMeta.bubbles,
complexType: eventMeta.complexType,
cancelable: eventMeta.cancelable,
composed: eventMeta.composed,
docs: eventMeta.docs.text,
docsTags: eventMeta.docs.tags,
deprecation: getDocsDeprecationText(eventMeta.docs.tags),
}));
};
/**
* Transforms the {@link d.CompilerStyleDoc} metadata for a component into a {@link d.JsonDocsStyle}, providing sensible
* defaults where needed.
* @param cmpMeta the metadata for a single Stencil component, which contains the compiler style metadata
* @returns a new series containing a {@link d.JsonDocsStyle} entry for each {@link d.CompilerStyleDoc} entry.
*/
export const getDocsStyles = (cmpMeta: d.ComponentCompilerMeta): d.JsonDocsStyle[] => {
if (!cmpMeta.styleDocs) {
return [];
}
return sortBy(
cmpMeta.styleDocs,
(compilerStyleDoc) => `${compilerStyleDoc.name.toLowerCase()},${compilerStyleDoc.mode.toLowerCase()}}`,
).map((compilerStyleDoc) => {
return {
name: compilerStyleDoc.name,
annotation: compilerStyleDoc.annotation || '',
docs: compilerStyleDoc.docs || '',
mode: compilerStyleDoc.mode && compilerStyleDoc.mode !== DEFAULT_STYLE_MODE ? compilerStyleDoc.mode : undefined,
};
});
};
const getDocsListeners = (listeners: d.ComponentCompilerListener[]): d.JsonDocsListener[] => {
return listeners.map((listener) => ({
event: listener.name,
target: listener.target,
capture: listener.capture,
passive: listener.passive,
}));
};
/**
* Get the text associated with a `@deprecated` tag, if one exists
* @param tags the tags associated with a JSDoc block on a node in the AST
* @returns the text associated with the first found `@deprecated` tag. If a `@deprecated` tag exists but does not
* have associated text, an empty string is returned. If no such tag is found, return `undefined`
*/
const getDocsDeprecationText = (tags: d.JsonDocsTag[]): string | undefined => {
const deprecation = tags.find((t) => t.name === 'deprecated');
if (deprecation) {
return deprecation.text || '';
}
return undefined;
};
const getDocsSlots = (tags: d.JsonDocsTag[]): d.JsonDocsSlot[] => {
return sortBy(
getNameText('slot', tags).map(([name, docs]) => ({ name, docs })),
(a) => a.name,
);
};
const getDocsParts = (vdom: string[], tags: d.JsonDocsTag[]): d.JsonDocsSlot[] => {
const docsParts = getNameText('part', tags).map(([name, docs]) => ({ name, docs }));
const vdomParts = vdom.map((name) => ({ name, docs: '' }));
return sortBy(
unique([...docsParts, ...vdomParts], (p) => p.name),
(p) => p.name,
);
};
/**
* Extract custom states documentation from component metadata
*
* @param cmpMeta the component metadata to extract custom states from
* @returns array of custom state documentation objects
*/
const getDocsCustomStates = (cmpMeta: d.ComponentCompilerMeta): d.JsonDocsCustomState[] => {
if (!cmpMeta.attachInternalsCustomStates || cmpMeta.attachInternalsCustomStates.length === 0) {
return [];
}
return sortBy(
cmpMeta.attachInternalsCustomStates.map((state) => ({
name: state.name,
initialValue: state.initialValue,
docs: state.docs || '',
})),
(state) => state.name,
);
};
export const getNameText = (name: string, tags: d.JsonDocsTag[]) => {
return tags
.filter((tag) => tag.name === name && tag.text)
.map(({ text }) => {
const [namePart, ...rest] = (' ' + text).split(' - ');
return [namePart.trim(), rest.join(' - ').trim()];
});
};
/**
* Attempts to read a pre-existing README.md file from disk, returning any content generated by the user.
*
* For simplicity's sake, it is assumed that all user-generated content will fall before {@link AUTO_GENERATE_COMMENT}
*
* @param compilerCtx the current compiler context
* @param readmePath the path to the README file to read
* @returns the user generated content that occurs before {@link AUTO_GENERATE_COMMENT}. If no user generated content
* exists, or if there was an issue reading the file, return `undefined`
*/
export const getUserReadmeContent = async (
compilerCtx: d.CompilerCtx,
readmePath: string,
): Promise => {
try {
const existingContent = await compilerCtx.fs.readFile(readmePath);
// subtract one to get everything up to, but not including the auto generated comment
const userContentIndex = existingContent.indexOf(AUTO_GENERATE_COMMENT) - 1;
if (userContentIndex >= 0) {
return existingContent.substring(0, userContentIndex);
}
} catch (e) {}
return undefined;
};
/**
* Generate documentation for a given component based on the provided JSDoc and README contents
* @param readme the contents of a component's README file, without any autogenerated contents
* @param jsdoc the JSDoc associated with the component's declaration
* @returns the generated documentation
*/
const generateDocs = (readme: string | undefined, jsdoc: d.CompilerJsDoc): string => {
const docs = jsdoc.text;
if (docs !== '' || !readme) {
// just return the existing docs if they exist. these would have been captured earlier in the compilation process.
// if they don't exist, and there's no README to process, return an empty string.
return docs;
}
/**
* Parse the README, storing the first section of content.
* Content is defined as the area between two non-consecutive lines that start with a '#':
* ```
* # Header 1
* This is some content
* # Header 2
* This is more content
* # Header 3
* Again, content
* ```
* In the example above, this chunk of code is designed to capture "This is some content"
*/
let isContent = false;
const lines = readme.split('\n');
const contentLines = [];
for (const line of lines) {
const isHeader = line.startsWith('#');
if (isHeader && isContent) {
// we were actively parsing content, but found a new header, break out
break;
}
if (!isHeader && !isContent) {
// we've found content for the first time, set this sentinel to `true`
isContent = true;
}
if (isContent) {
// we're actively parsing the first found block of content, add it to our list for later
contentLines.push(line);
}
}
return contentLines.join('\n').trim();
};
/**
* This function is responsible for reading the contents of all markdown files in a provided `usage` directory and
* returning their contents
* @param compilerCtx the current compiler context
* @param usagesDir the directory to read usage markdown files from
* @returns an object that maps the filename containing the usage example, to the file's contents. If an error occurs,
* an empty object is returned.
*/
const generateUsages = async (compilerCtx: d.CompilerCtx, usagesDir: string): Promise => {
const rtn: d.JsonDocsUsage = {};
try {
const usageFilePaths = await compilerCtx.fs.readdir(usagesDir);
const usages: d.JsonDocsUsage = {};
await Promise.all(
usageFilePaths.map(async (f) => {
if (!f.isFile) {
return;
}
const fileName = basename(f.relPath);
if (!fileName.toLowerCase().endsWith('.md')) {
return;
}
const parts = fileName.split('.');
parts.pop();
const key = parts.join('.');
usages[key] = await compilerCtx.fs.readFile(f.absPath);
}),
);
Object.keys(usages)
.sort()
.forEach((key) => {
rtn[key] = usages[key];
});
} catch (e) {}
return rtn;
};
================================================
FILE: src/compiler/docs/json/index.ts
================================================
import { isOutputTargetDocsJson, join } from '@utils';
import type * as d from '../../../declarations';
export const generateJsonDocs = async (
config: d.ValidatedConfig,
compilerCtx: d.CompilerCtx,
docsData: d.JsonDocs,
outputTargets: d.OutputTarget[],
) => {
const jsonOutputTargets = outputTargets.filter(isOutputTargetDocsJson);
if (jsonOutputTargets.length === 0) {
return;
}
const docsDtsPath = join(config.sys.getCompilerExecutingPath(), '..', '..', 'internal', 'stencil-public-docs.d.ts');
let docsDts = await compilerCtx.fs.readFile(docsDtsPath);
// this file was written by dts-bundle-generator, which uses tabs for
// indentation. Instead, let's replace those with spaces!
docsDts = docsDts
.split('\n')
.map((line) => line.replace(/\t/g, ' '))
.join('\n');
const typesContent = `
/**
* This is an autogenerated file created by the Stencil compiler.
* DO NOT MODIFY IT MANUALLY
*/
${docsDts}
declare const _default: JsonDocs;
export default _default;
`;
const json = {
...docsData,
components: docsData.components.map((cmp) => ({
filePath: cmp.filePath,
encapsulation: cmp.encapsulation,
tag: cmp.tag,
readme: cmp.readme,
docs: cmp.docs,
docsTags: cmp.docsTags,
usage: cmp.usage,
props: cmp.props,
methods: cmp.methods,
events: cmp.events,
listeners: cmp.listeners,
styles: cmp.styles,
slots: cmp.slots,
parts: cmp.parts,
states: cmp.customStates,
dependents: cmp.dependents,
dependencies: cmp.dependencies,
dependencyGraph: cmp.dependencyGraph,
deprecation: cmp.deprecation,
})),
};
const jsonContent = JSON.stringify(json, null, 2);
await Promise.all(
jsonOutputTargets.map((jsonOutput) => {
return writeDocsOutput(compilerCtx, jsonOutput, jsonContent, typesContent);
}),
);
};
export const writeDocsOutput = async (
compilerCtx: d.CompilerCtx,
jsonOutput: d.OutputTargetDocsJson,
jsonContent: string,
typesContent: string,
) => {
return Promise.all([
compilerCtx.fs.writeFile(jsonOutput.file, jsonContent),
jsonOutput.typesFile ? compilerCtx.fs.writeFile(jsonOutput.typesFile, typesContent) : (Promise.resolve() as any),
]);
};
================================================
FILE: src/compiler/docs/readme/docs-util.ts
================================================
export class MarkdownTable {
private rows: RowData[] = [];
addHeader(data: string[]) {
this.addRow(data, true);
}
addRow(data: string[], isHeader = false) {
const colData: ColumnData[] = [];
data.forEach((text) => {
const col: ColumnData = {
text: escapeMarkdownTableColumn(text),
width: text.length,
};
colData.push(col);
});
this.rows.push({
columns: colData,
isHeader: isHeader,
});
}
toMarkdown() {
return createTable(this.rows);
}
}
const escapeMarkdownTableColumn = (text: string) => {
text = text.replace(/\r?\n/g, ' ');
text = text.replace(/\|/g, '\\|');
return text;
};
const createTable = (rows: RowData[]) => {
const content: string[] = [];
if (rows.length === 0) {
return content;
}
normalizeColumCount(rows);
normalizeColumnWidth(rows);
const th = rows.find((r) => r.isHeader);
if (th) {
const headerRow = createRow(th);
content.push(headerRow);
content.push(createBorder(th));
}
const tds = rows.filter((r) => !r.isHeader);
tds.forEach((td) => {
content.push(createRow(td));
});
return content;
};
const createBorder = (th: RowData) => {
const border: RowData = {
columns: [],
isHeader: false,
};
th.columns.forEach((c) => {
const borderCol: ColumnData = {
text: '',
width: c.width,
};
while (borderCol.text.length < borderCol.width) {
borderCol.text += '-';
}
border.columns.push(borderCol);
});
return createRow(border);
};
const createRow = (row: RowData) => {
const content: string[] = ['| '];
row.columns.forEach((c) => {
content.push(c.text);
content.push(' | ');
});
return content.join('').trim();
};
const normalizeColumCount = (rows: RowData[]) => {
let columnCount = 0;
rows.forEach((r) => {
if (r.columns.length > columnCount) {
columnCount = r.columns.length;
}
});
rows.forEach((r) => {
while (r.columns.length < columnCount) {
r.columns.push({
text: ``,
width: 0,
});
}
});
};
const normalizeColumnWidth = (rows: RowData[]) => {
const columnCount = rows[0].columns.length;
for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
let longestText = 0;
rows.forEach((r) => {
const col = r.columns[columnIndex];
if (col.text.length > longestText) {
longestText = col.text.length;
}
});
rows.forEach((r) => {
const col = r.columns[columnIndex];
col.width = longestText;
while (col.text.length < longestText) {
col.text += ' ';
}
});
}
};
/**
* Checks if a given string is a valid hexadecimal color representation.
*
* @param str - The string to be checked.
* @returns `true` if the string is a valid hex color (e.g., '#FF00AA', '#f0f'), `false` otherwise.
*
* @example
* isHexColor('#FF00AA'); // true
* isHexColor('#f0f'); // true
* isHexColor('#abcde'); // false (too many characters)
* isHexColor('FF00AA'); // false (missing #)
*/
export const isHexColor = (str: string): boolean => {
const hexColorRegex = /^#([0-9A-Fa-f]{3}){1,2}$/;
return hexColorRegex.test(str);
};
interface ColumnData {
text: string;
width: number;
}
interface RowData {
columns: ColumnData[];
isHeader?: boolean;
}
================================================
FILE: src/compiler/docs/readme/index.ts
================================================
import { isOutputTargetDocsReadme } from '@utils';
import type * as d from '../../../declarations';
import { generateReadme } from './output-docs';
export const generateReadmeDocs = async (
config: d.ValidatedConfig,
compilerCtx: d.CompilerCtx,
docsData: d.JsonDocs,
outputTargets: d.OutputTarget[],
) => {
const readmeOutputTargets = outputTargets.filter(isOutputTargetDocsReadme);
if (readmeOutputTargets.length === 0) {
return;
}
const strictCheck = readmeOutputTargets.some((o) => o.strict);
if (strictCheck) {
strictCheckDocs(config, docsData);
}
await Promise.all(
docsData.components.map((cmpData) => {
return generateReadme(config, compilerCtx, readmeOutputTargets, cmpData, docsData.components);
}),
);
};
export const strictCheckDocs = (config: d.ValidatedConfig, docsData: d.JsonDocs) => {
docsData.components.forEach((component) => {
component.props.forEach((prop) => {
if (!prop.docs && prop.deprecation === undefined) {
config.logger.warn(`Property "${prop.name}" of "${component.tag}" is not documented. ${component.filePath}`);
}
});
component.methods.forEach((method) => {
if (!method.docs && method.deprecation === undefined) {
config.logger.warn(`Method "${method.name}" of "${component.tag}" is not documented. ${component.filePath}`);
}
});
component.events.forEach((ev) => {
if (!ev.docs && ev.deprecation === undefined) {
config.logger.warn(`Event "${ev.event}" of "${component.tag}" is not documented. ${component.filePath}`);
}
});
component.parts.forEach((ev) => {
if (ev.docs === '') {
config.logger.warn(`Part "${ev.name}" of "${component.tag}" is not documented. ${component.filePath}`);
}
});
});
};
================================================
FILE: src/compiler/docs/readme/markdown-css-props.ts
================================================
import type * as d from '../../../declarations';
import { MarkdownTable } from './docs-util';
export const stylesToMarkdown = (styles: d.JsonDocsStyle[]) => {
const content: string[] = [];
if (styles.length === 0) {
return content;
}
content.push(`## CSS Custom Properties`);
content.push(``);
const table = new MarkdownTable();
table.addHeader(['Name', 'Description']);
styles.forEach((style) => {
table.addRow([`\`${style.name}\``, style.docs]);
});
content.push(...table.toMarkdown());
content.push(``);
content.push(``);
return content;
};
================================================
FILE: src/compiler/docs/readme/markdown-custom-states.ts
================================================
import type * as d from '../../../declarations';
import { MarkdownTable } from './docs-util';
/**
* Converts a list of Custom States metadata to a table written in Markdown
* @param customStates the Custom States metadata to convert
* @returns a list of strings that make up the Markdown table
*/
export const customStatesToMarkdown = (customStates: d.JsonDocsCustomState[]): ReadonlyArray => {
const content: string[] = [];
if (customStates.length === 0) {
return content;
}
content.push(`## Custom States`);
content.push(``);
const table = new MarkdownTable();
table.addHeader(['State', 'Initial Value', 'Description']);
customStates.forEach((state) => {
table.addRow([`\`:state(${state.name})\``, state.initialValue ? '`true`' : '`false`', state.docs]);
});
content.push(...table.toMarkdown());
content.push(``);
content.push(``);
return content;
};
================================================
FILE: src/compiler/docs/readme/markdown-dependencies.ts
================================================
import { normalizePath, relative } from '@utils';
import type * as d from '../../../declarations';
export const depsToMarkdown = (cmp: d.JsonDocsComponent, cmps: d.JsonDocsComponent[], config: d.ValidatedConfig) => {
const content: string[] = [];
const deps = Object.entries(cmp.dependencyGraph);
if (deps.length === 0) {
return content;
}
content.push(`## Dependencies`);
content.push(``);
if (cmp.dependents.length > 0) {
const usedBy = cmp.dependents.map((tag) => ' - ' + getCmpLink(cmp, tag, cmps));
content.push(`### Used by`);
content.push(``);
content.push(...usedBy);
content.push(``);
}
if (cmp.dependencies.length > 0) {
const dependsOn = cmp.dependencies.map((tag) => '- ' + getCmpLink(cmp, tag, cmps));
content.push(`### Depends on`);
content.push(``);
content.push(...dependsOn);
content.push(``);
}
content.push(`### Graph`);
content.push('```mermaid');
content.push('graph TD;');
deps.forEach(([key, deps]) => {
deps.forEach((dep) => {
content.push(` ${key} --> ${dep}`);
});
});
const { background, textColor } = config.docs.markdown.targetComponent;
content.push(` style ${cmp.tag} fill:${background},stroke:${textColor},stroke-width:4px`);
content.push('```');
content.push(``);
return content;
};
const getCmpLink = (from: d.JsonDocsComponent, to: string, cmps: d.JsonDocsComponent[]) => {
const destCmp = cmps.find((c) => c.tag === to);
if (destCmp) {
const cmpRelPath = normalizePath(relative(from.dirPath, destCmp.dirPath));
return `[${to}](${cmpRelPath})`;
}
return to;
};
================================================
FILE: src/compiler/docs/readme/markdown-events.ts
================================================
import type * as d from '../../../declarations';
import { MarkdownTable } from './docs-util';
export const eventsToMarkdown = (events: d.JsonDocsEvent[]) => {
const content: string[] = [];
if (events.length === 0) {
return content;
}
content.push(`## Events`);
content.push(``);
const table = new MarkdownTable();
table.addHeader(['Event', 'Description', 'Type']);
events.forEach((ev) => {
table.addRow([`\`${ev.event}\``, getDocsField(ev), `\`CustomEvent<${ev.detail}>\``]);
});
content.push(...table.toMarkdown());
content.push(``);
content.push(``);
return content;
};
const getDocsField = (prop: d.JsonDocsEvent) => {
return `${
prop.deprecation !== undefined
? `**[DEPRECATED]** ${prop.deprecation}**[DEPRECATED]** ${prop.deprecation} => {
if (!overview) {
return [];
}
const content: string[] = [];
content.push(`## Overview`);
content.push('');
content.push(`${overview.trim()}`);
content.push('');
return content;
};
================================================
FILE: src/compiler/docs/readme/markdown-parts.ts
================================================
import type * as d from '../../../declarations';
import { MarkdownTable } from './docs-util';
/**
* Converts a list of Shadow Parts metadata to a table written in Markdown
* @param parts the Shadow parts metadata to convert
* @returns a list of strings that make up the Markdown table
*/
export const partsToMarkdown = (parts: d.JsonDocsPart[]): ReadonlyArray => {
const content: string[] = [];
if (parts.length === 0) {
return content;
}
content.push(`## Shadow Parts`);
content.push(``);
const table = new MarkdownTable();
table.addHeader(['Part', 'Description']);
parts.forEach((style) => {
table.addRow([style.name === '' ? '' : `\`"${style.name}"\``, style.docs]);
});
content.push(...table.toMarkdown());
content.push(``);
content.push(``);
return content;
};
================================================
FILE: src/compiler/docs/readme/markdown-props.ts
================================================
import type * as d from '../../../declarations';
import { MarkdownTable } from './docs-util';
export const propsToMarkdown = (props: d.JsonDocsProp[]) => {
const content: string[] = [];
if (props.length === 0) {
return content;
}
content.push(`## Properties`);
content.push(``);
const table = new MarkdownTable();
table.addHeader(['Property', 'Attribute', 'Description', 'Type', 'Default']);
props.forEach((prop) => {
table.addRow([
getPropertyField(prop),
getAttributeField(prop),
getDocsField(prop),
getTypeField(prop),
getDefaultValueField(prop),
]);
});
content.push(...table.toMarkdown());
content.push(``);
content.push(``);
return content;
};
const getPropertyField = (prop: d.JsonDocsProp) => {
return `\`${prop.name}\`${prop.required ? ' _(required)_' : ''}`;
};
const getAttributeField = (prop: d.JsonDocsProp) => {
return prop.attr ? `\`${prop.attr}\`` : '--';
};
const getDocsField = (prop: d.JsonDocsProp) => {
return `${
prop.deprecation !== undefined
? `**[DEPRECATED]** ${prop.deprecation} => {
const content: string[] = [];
if (slots.length === 0) {
return content;
}
content.push(`## Slots`);
content.push(``);
const table = new MarkdownTable();
table.addHeader(['Slot', 'Description']);
slots.forEach((style) => {
table.addRow([style.name === '' ? '' : `\`"${style.name}"\``, style.docs]);
});
content.push(...table.toMarkdown());
content.push(``);
content.push(``);
return content;
};
================================================
FILE: src/compiler/docs/readme/markdown-usage.ts
================================================
import { toTitleCase } from '@utils';
import type * as d from '../../../declarations';
export const usageToMarkdown = (usages: d.JsonDocsUsage) => {
const content: string[] = [];
const merged = mergeUsages(usages);
if (merged.length === 0) {
return content;
}
content.push(`## Usage`);
merged.forEach(({ name, text }) => {
content.push('');
content.push(`### ${toTitleCase(name)}`);
content.push('');
content.push(text);
content.push('');
}),
content.push('');
content.push('');
return content;
};
export const mergeUsages = (usages: d.JsonDocsUsage) => {
const keys = Object.keys(usages);
const map = new Map();
keys.forEach((key) => {
const usage = usages[key].trim();
const array = map.get(usage) || [];
array.push(key);
map.set(usage, array);
});
const merged: { name: string; text: string }[] = [];
map.forEach((value, key) => {
merged.push({
name: value.join(' / '),
text: key,
});
});
return merged;
};
================================================
FILE: src/compiler/docs/readme/output-docs.ts
================================================
import { join, normalizePath, relative } from '@utils';
import type * as d from '../../../declarations';
import { AUTO_GENERATE_COMMENT } from '../constants';
import { getUserReadmeContent } from '../generate-doc-data';
import { stylesToMarkdown } from './markdown-css-props';
import { customStatesToMarkdown } from './markdown-custom-states';
import { depsToMarkdown } from './markdown-dependencies';
import { eventsToMarkdown } from './markdown-events';
import { methodsToMarkdown } from './markdown-methods';
import { overviewToMarkdown } from './markdown-overview';
import { partsToMarkdown } from './markdown-parts';
import { propsToMarkdown } from './markdown-props';
import { slotsToMarkdown } from './markdown-slots';
import { usageToMarkdown } from './markdown-usage';
/**
* Generate a README for a given component and write it to disk.
*
* Typically the README is going to be a 'sibling' to the component's source
* code (i.e. written to the same directory) but the user may also configure a
* custom output directory by setting {@link d.OutputTargetDocsReadme.dir}.
*
* Output readme files also include {@link AUTO_GENERATE_COMMENT}, and any
* text located _above_ that comment is preserved when the new readme is written
* to disk.
*
* @param config a validated Stencil config
* @param compilerCtx the current compiler context
* @param readmeOutputs docs-readme output targets
* @param docsData documentation data for the component of interest
* @param cmps metadata for all the components in the project
*/
export const generateReadme = async (
config: d.ValidatedConfig,
compilerCtx: d.CompilerCtx,
readmeOutputs: d.OutputTargetDocsReadme[],
docsData: d.JsonDocsComponent,
cmps: d.JsonDocsComponent[],
) => {
const isUpdate = !!docsData.readme;
const userContent = isUpdate ? docsData.readme : getDefaultReadme(docsData);
await Promise.all(
readmeOutputs.map(async (readmeOutput) => {
if (readmeOutput.dir) {
const relativeReadmePath = relative(config.srcDir, docsData.readmePath);
const readmeOutputPath = join(readmeOutput.dir, relativeReadmePath);
const currentReadmeContent =
readmeOutput.overwriteExisting === true
? // Overwrite explicitly requested: always use the provided user content.
userContent
: normalizePath(readmeOutput.dir) !== normalizePath(config.srcDir)
? (readmeOutput.overwriteExisting === 'if-missing' &&
// Validate a file exists at the output path
(await compilerCtx.fs.access(readmeOutputPath))) ||
// False and undefined case: follow the changes made in #5648
(readmeOutput.overwriteExisting ?? false) === false
? // Existing file found: The user set a custom `.dir` property, which is
// where we're going to write the updated README. We need to read the
// non-automatically generated content from that file and preserve that.
await getUserReadmeContent(compilerCtx, readmeOutputPath)
: // No existing file found: use the provided user content.
userContent
: // Default case: writing to srcDir, so use the provided user content.
userContent;
// CSS Custom Properties preservation is now handled centrally in outputDocs
const readmeContent = generateMarkdown(currentReadmeContent, docsData, cmps, readmeOutput, config);
const results = await compilerCtx.fs.writeFile(readmeOutputPath, readmeContent);
if (results.changedContent) {
if (isUpdate) {
config.logger.info(`updated readme docs: ${docsData.tag}`);
} else {
config.logger.info(`created readme docs: ${docsData.tag}`);
}
}
}
}),
);
};
export const generateMarkdown = (
userContent: string | undefined,
cmp: d.JsonDocsComponent,
cmps: d.JsonDocsComponent[],
readmeOutput: d.OutputTargetDocsReadme,
config?: d.ValidatedConfig,
) => {
//If the readmeOutput.dependencies is true or undefined the dependencies will be generated.
const dependencies = readmeOutput.dependencies !== false ? depsToMarkdown(cmp, cmps, config) : [];
return [
userContent || '',
AUTO_GENERATE_COMMENT,
'',
'',
...getDocsDeprecation(cmp),
...overviewToMarkdown(cmp.overview),
...usageToMarkdown(cmp.usage),
...propsToMarkdown(cmp.props),
...eventsToMarkdown(cmp.events),
...methodsToMarkdown(cmp.methods),
...slotsToMarkdown(cmp.slots),
...partsToMarkdown(cmp.parts),
...customStatesToMarkdown(cmp.customStates),
...stylesToMarkdown(cmp.styles),
...dependencies,
`----------------------------------------------`,
'',
readmeOutput.footer,
'',
].join('\n');
};
const getDocsDeprecation = (cmp: d.JsonDocsComponent) => {
if (cmp.deprecation !== undefined) {
return [`> **[DEPRECATED]** ${cmp.deprecation}`, ''];
}
return [];
};
/**
* Get a minimal default README for a Stencil component
*
* @param docsData documentation data for the component of interest
* @returns a minimal README template for that component
*/
const getDefaultReadme = (docsData: d.JsonDocsComponent) => {
return [`# ${docsData.tag}`, '', '', ''].join('\n');
};
/**
* Extract the existing CSS Custom Properties section from a README file.
* This is used to preserve CSS props documentation when running `stencil docs`
* without building styles.
*
* @param compilerCtx the current compiler context
* @param readmePath the path to the README file to read
* @returns array of CSS custom properties styles, or undefined if none found
*/
export const extractExistingCssProps = async (
compilerCtx: d.CompilerCtx,
readmePath: string,
): Promise => {
try {
const existingContent = await compilerCtx.fs.readFile(readmePath);
// Find the CSS Custom Properties section
const cssPropsSectionMatch = existingContent.match(
/## CSS Custom Properties\s*\n\s*\n([\s\S]*?)(?=\n##|\n-{4,}|$)/,
);
if (!cssPropsSectionMatch) {
return undefined;
}
const cssPropsSection = cssPropsSectionMatch[1];
const styles: d.JsonDocsStyle[] = [];
// Parse the markdown table to extract CSS custom properties
// Table format:
// | Name | Description |
// | ---- | ----------- |
// | `--prop-name` | Description text |
const lines = cssPropsSection.split('\n');
let inTable = false;
for (const line of lines) {
const trimmedLine = line.trim();
// Skip header and separator rows
if (trimmedLine.startsWith('| Name') || trimmedLine.startsWith('| ---')) {
inTable = true;
continue;
}
// Parse table rows
if (inTable && trimmedLine.startsWith('|')) {
const parts = trimmedLine
.split('|')
.map((p) => p.trim())
.filter((p) => p);
if (parts.length >= 2) {
// Extract the CSS variable name (remove backticks)
const name = parts[0].replace(/`/g, '').trim();
const docs = parts[1].trim();
if (name.startsWith('--')) {
styles.push({
name,
docs,
annotation: 'prop',
mode: undefined,
});
}
}
}
}
return styles.length > 0 ? styles : undefined;
} catch (e) {
return undefined;
}
};
================================================
FILE: src/compiler/docs/style-docs.ts
================================================
import type * as d from '../../declarations';
/**
* Parse CSS docstrings that Stencil supports, as documented here:
* https://stenciljs.com/docs/docs-json#css-variables
*
* Docstrings found in the supplied style text will be added to the
* `styleDocs` param
*
* @param styleDocs the array to hold formatted CSS docstrings
* @param styleText the CSS text we're working with
* @param mode a mode associated with the parsed style, if applicable (e.g. this is not applicable for global styles)
*/
export function parseStyleDocs(styleDocs: d.StyleDoc[], styleText: string | null, mode?: string | undefined) {
if (typeof styleText !== 'string') {
return;
}
// Using `match` allows us to know which substring matched the regex and the starting
// index at which the match was found
let match = styleText.match(CSS_DOC_START);
while (match !== null) {
styleText = styleText.substring(match.index + match[0].length);
const endIndex = styleText.indexOf(CSS_DOC_END);
if (endIndex === -1) {
break;
}
const comment = styleText.substring(0, endIndex);
parseCssComment(styleDocs, comment, mode);
styleText = styleText.substring(endIndex + CSS_DOC_END.length);
match = styleText.match(CSS_DOC_START);
}
}
/**
* Parse a CSS comment string and insert it into the provided array of
* style docstrings.
*
* @param styleDocs an array which will be modified with the docstring
* @param comment the comment string
* @param mode a mode associated with the parsed style, if applicable (e.g. this is not applicable for global styles)
*/
function parseCssComment(styleDocs: d.StyleDoc[], comment: string, mode: string | undefined): void {
/**
* @prop --max-width: Max width of the alert
*/
// (the above is an example of what these comments might look like)
const lines = comment.split(/\r?\n/).map((line) => {
line = line.trim();
while (line.startsWith('*')) {
line = line.substring(1).trim();
}
return line;
});
comment = lines.join(' ').replace(/\t/g, ' ').trim();
while (comment.includes(' ')) {
comment = comment.replace(' ', ' ');
}
const docs = comment.split(CSS_PROP_ANNOTATION);
docs.forEach((d) => {
const cssDocument = d.trim();
if (!cssDocument.startsWith(`--`)) {
return;
}
const splt = cssDocument.split(`:`);
const styleDoc: d.StyleDoc = {
name: splt[0].trim(),
docs: (splt.shift() && splt.join(`:`)).trim(),
annotation: 'prop',
mode,
};
if (!styleDocs.some((c) => c.name === styleDoc.name && c.annotation === 'prop')) {
styleDocs.push(styleDoc);
}
});
}
/**
* Opening syntax for a CSS docstring.
* This will match a traditional docstring or a "loud" comment in sass
*/
const CSS_DOC_START = /\/\*(\*|\!)/;
/**
* Closing syntax for a CSS docstring
*/
const CSS_DOC_END = '*/';
/**
* The `@prop` annotation we support within CSS docstrings
*/
const CSS_PROP_ANNOTATION = '@prop';
================================================
FILE: src/compiler/docs/test/custom-elements-manifest.spec.ts
================================================
import { mockCompilerCtx, mockValidatedConfig } from '@stencil/core/testing';
import type * as d from '../../../declarations';
import { generateCustomElementsManifestDocs } from '../cem';
describe('custom-elements-manifest', () => {
let compilerCtx: d.CompilerCtx;
let writeFileSpy: jest.SpyInstance;
beforeEach(() => {
const config = mockValidatedConfig();
compilerCtx = mockCompilerCtx(config);
writeFileSpy = jest.spyOn(compilerCtx.fs, 'writeFile');
});
afterEach(() => {
writeFileSpy.mockRestore();
});
it('does nothing when no custom-elements-manifest output targets are configured', async () => {
const docsData: d.JsonDocs = {
timestamp: 'test',
compiler: { name: '@stencil/core', version: '1.0.0', typescriptVersion: '4.0.0' },
components: [],
typeLibrary: {},
};
await generateCustomElementsManifestDocs(compilerCtx, docsData, []);
expect(writeFileSpy).not.toHaveBeenCalled();
});
it('generates manifest with correct schema version', async () => {
const docsData: d.JsonDocs = {
timestamp: 'test',
compiler: { name: '@stencil/core', version: '1.0.0', typescriptVersion: '4.0.0' },
components: [],
typeLibrary: {},
};
const outputTargets: d.OutputTargetDocsCustomElementsManifest[] = [
{ type: 'docs-custom-elements-manifest', file: '/output/custom-elements.json' },
];
await generateCustomElementsManifestDocs(compilerCtx, docsData, outputTargets);
expect(writeFileSpy).toHaveBeenCalledTimes(1);
const writtenContent = JSON.parse(writeFileSpy.mock.calls[0][1]);
expect(writtenContent.schemaVersion).toBe('2.1.0');
expect(writtenContent.modules).toEqual([]);
});
it('generates module for each component file', async () => {
const docsData: d.JsonDocs = {
timestamp: 'test',
compiler: { name: '@stencil/core', version: '1.0.0', typescriptVersion: '4.0.0' },
components: [
createMockComponent({
tag: 'my-component',
filePath: 'src/components/my-component/my-component.tsx',
}),
],
typeLibrary: {},
};
const outputTargets: d.OutputTargetDocsCustomElementsManifest[] = [
{ type: 'docs-custom-elements-manifest', file: '/output/custom-elements.json' },
];
await generateCustomElementsManifestDocs(compilerCtx, docsData, outputTargets);
const writtenContent = JSON.parse(writeFileSpy.mock.calls[0][1]);
expect(writtenContent.modules).toHaveLength(1);
expect(writtenContent.modules[0].kind).toBe('javascript-module');
expect(writtenContent.modules[0].path).toBe('src/components/my-component/my-component.tsx');
});
it('converts tag name to PascalCase class name', async () => {
const docsData: d.JsonDocs = {
timestamp: 'test',
compiler: { name: '@stencil/core', version: '1.0.0', typescriptVersion: '4.0.0' },
components: [
createMockComponent({
tag: 'my-awesome-component',
filePath: 'src/my-component.tsx',
}),
],
typeLibrary: {},
};
const outputTargets: d.OutputTargetDocsCustomElementsManifest[] = [
{ type: 'docs-custom-elements-manifest', file: '/output/custom-elements.json' },
];
await generateCustomElementsManifestDocs(compilerCtx, docsData, outputTargets);
const writtenContent = JSON.parse(writeFileSpy.mock.calls[0][1]);
const declaration = writtenContent.modules[0].declarations[0];
expect(declaration.name).toBe('MyAwesomeComponent');
expect(declaration.tagName).toBe('my-awesome-component');
});
it('includes component description', async () => {
const docsData: d.JsonDocs = {
timestamp: 'test',
compiler: { name: '@stencil/core', version: '1.0.0', typescriptVersion: '4.0.0' },
components: [
createMockComponent({
tag: 'my-component',
filePath: 'src/my-component.tsx',
docs: 'This is a test component',
}),
],
typeLibrary: {},
};
const outputTargets: d.OutputTargetDocsCustomElementsManifest[] = [
{ type: 'docs-custom-elements-manifest', file: '/output/custom-elements.json' },
];
await generateCustomElementsManifestDocs(compilerCtx, docsData, outputTargets);
const writtenContent = JSON.parse(writeFileSpy.mock.calls[0][1]);
const declaration = writtenContent.modules[0].declarations[0];
expect(declaration.description).toBe('This is a test component');
});
it('includes attributes from props with attr set', async () => {
const docsData: d.JsonDocs = {
timestamp: 'test',
compiler: { name: '@stencil/core', version: '1.0.0', typescriptVersion: '4.0.0' },
components: [
createMockComponent({
tag: 'my-component',
filePath: 'src/my-component.tsx',
props: [
{
name: 'firstName',
attr: 'first-name',
type: 'string',
docs: 'The first name',
default: "'John'",
mutable: false,
reflectToAttr: true,
docsTags: [],
values: [],
optional: false,
required: false,
getter: false,
setter: false,
},
],
}),
],
typeLibrary: {},
};
const outputTargets: d.OutputTargetDocsCustomElementsManifest[] = [
{ type: 'docs-custom-elements-manifest', file: '/output/custom-elements.json' },
];
await generateCustomElementsManifestDocs(compilerCtx, docsData, outputTargets);
const writtenContent = JSON.parse(writeFileSpy.mock.calls[0][1]);
const declaration = writtenContent.modules[0].declarations[0];
expect(declaration.attributes).toHaveLength(1);
expect(declaration.attributes[0]).toEqual({
name: 'first-name',
description: 'The first name',
type: { text: 'string' },
default: "'John'",
fieldName: 'firstName',
});
});
it('includes members (fields) from props', async () => {
const docsData: d.JsonDocs = {
timestamp: 'test',
compiler: { name: '@stencil/core', version: '1.0.0', typescriptVersion: '4.0.0' },
components: [
createMockComponent({
tag: 'my-component',
filePath: 'src/my-component.tsx',
props: [
{
name: 'count',
type: 'number',
docs: 'The count value',
default: '0',
mutable: false,
reflectToAttr: false,
docsTags: [],
values: [],
optional: false,
required: false,
getter: false,
setter: false,
},
],
}),
],
typeLibrary: {},
};
const outputTargets: d.OutputTargetDocsCustomElementsManifest[] = [
{ type: 'docs-custom-elements-manifest', file: '/output/custom-elements.json' },
];
await generateCustomElementsManifestDocs(compilerCtx, docsData, outputTargets);
const writtenContent = JSON.parse(writeFileSpy.mock.calls[0][1]);
const declaration = writtenContent.modules[0].declarations[0];
const field = declaration.members.find((m: any) => m.kind === 'field');
expect(field).toBeDefined();
expect(field.name).toBe('count');
expect(field.type).toEqual({ text: 'number' });
expect(field.readonly).toBe(true);
});
it('includes methods', async () => {
const docsData: d.JsonDocs = {
timestamp: 'test',
compiler: { name: '@stencil/core', version: '1.0.0', typescriptVersion: '4.0.0' },
components: [
createMockComponent({
tag: 'my-component',
filePath: 'src/my-component.tsx',
methods: [
{
name: 'doSomething',
docs: 'Does something',
docsTags: [],
returns: { type: 'Promise', docs: 'Returns nothing' },
signature: 'doSomething(value: string) => Promise',
parameters: [{ name: 'value', type: 'string', docs: 'The value to use' }],
complexType: {
signature: '(value: string) => Promise',
parameters: [{ name: 'value', type: 'string', docs: 'The value to use' }],
return: 'Promise',
references: {},
},
},
],
}),
],
typeLibrary: {},
};
const outputTargets: d.OutputTargetDocsCustomElementsManifest[] = [
{ type: 'docs-custom-elements-manifest', file: '/output/custom-elements.json' },
];
await generateCustomElementsManifestDocs(compilerCtx, docsData, outputTargets);
const writtenContent = JSON.parse(writeFileSpy.mock.calls[0][1]);
const declaration = writtenContent.modules[0].declarations[0];
const method = declaration.members.find((m: any) => m.kind === 'method');
expect(method).toBeDefined();
expect(method.name).toBe('doSomething');
expect(method.description).toBe('Does something');
expect(method.parameters).toHaveLength(1);
expect(method.return.type).toEqual({ text: 'Promise' });
});
it('includes type references from complexType', async () => {
const docsData: d.JsonDocs = {
timestamp: 'test',
compiler: { name: '@stencil/core', version: '1.0.0', typescriptVersion: '4.0.0' },
components: [
createMockComponent({
tag: 'my-component',
filePath: 'src/my-component.tsx',
props: [
{
name: 'items',
type: 'MyItem[]',
docs: 'Array of items',
mutable: false,
reflectToAttr: false,
docsTags: [],
values: [],
optional: false,
required: false,
getter: false,
setter: false,
complexType: {
original: 'MyItem[]',
resolved: '{ id: string; name: string }[]',
references: {
MyItem: {
location: 'import',
path: './types',
id: 'src/types.ts::MyItem',
},
},
},
},
{
name: 'element',
type: 'HTMLElement',
docs: 'An HTML element',
mutable: false,
reflectToAttr: false,
docsTags: [],
values: [],
optional: false,
required: false,
getter: false,
setter: false,
complexType: {
original: 'HTMLElement',
resolved: 'HTMLElement',
references: {
HTMLElement: {
location: 'global',
path: '',
id: 'global::HTMLElement',
},
},
},
},
],
events: [
{
event: 'itemSelected',
docs: 'Fired when item is selected',
detail: 'MyItem',
bubbles: true,
cancelable: false,
composed: true,
docsTags: [],
complexType: {
original: 'MyItem',
resolved: '{ id: string; name: string }',
references: {
MyItem: {
location: 'import',
path: './types',
id: 'src/types.ts::MyItem',
},
},
},
},
],
}),
],
typeLibrary: {},
};
const outputTargets: d.OutputTargetDocsCustomElementsManifest[] = [
{ type: 'docs-custom-elements-manifest', file: '/output/custom-elements.json' },
];
await generateCustomElementsManifestDocs(compilerCtx, docsData, outputTargets);
const writtenContent = JSON.parse(writeFileSpy.mock.calls[0][1]);
const declaration = writtenContent.modules[0].declarations[0];
// Check prop with imported type reference
const itemsField = declaration.members.find((m: any) => m.name === 'items');
expect(itemsField.type.text).toBe('MyItem[]');
expect(itemsField.type.references).toEqual([{ name: 'MyItem', module: './types' }]);
// Check prop with global type reference
const elementField = declaration.members.find((m: any) => m.name === 'element');
expect(elementField.type.text).toBe('HTMLElement');
expect(elementField.type.references).toEqual([{ name: 'HTMLElement', package: 'global:' }]);
// Check event with type reference
const event = declaration.events[0];
expect(event.type.text).toBe('CustomEvent');
expect(event.type.references).toEqual([{ name: 'MyItem', module: './types' }]);
});
it('includes events', async () => {
const docsData: d.JsonDocs = {
timestamp: 'test',
compiler: { name: '@stencil/core', version: '1.0.0', typescriptVersion: '4.0.0' },
components: [
createMockComponent({
tag: 'my-component',
filePath: 'src/my-component.tsx',
events: [
{
event: 'myEvent',
docs: 'Fired when something happens',
detail: 'string',
bubbles: true,
cancelable: true,
composed: true,
docsTags: [],
complexType: {
original: 'string',
resolved: 'string',
references: {},
},
},
],
}),
],
typeLibrary: {},
};
const outputTargets: d.OutputTargetDocsCustomElementsManifest[] = [
{ type: 'docs-custom-elements-manifest', file: '/output/custom-elements.json' },
];
await generateCustomElementsManifestDocs(compilerCtx, docsData, outputTargets);
const writtenContent = JSON.parse(writeFileSpy.mock.calls[0][1]);
const declaration = writtenContent.modules[0].declarations[0];
expect(declaration.events).toHaveLength(1);
expect(declaration.events[0]).toEqual({
name: 'myEvent',
description: 'Fired when something happens',
type: { text: 'CustomEvent' },
});
});
it('includes slots', async () => {
const docsData: d.JsonDocs = {
timestamp: 'test',
compiler: { name: '@stencil/core', version: '1.0.0', typescriptVersion: '4.0.0' },
components: [
createMockComponent({
tag: 'my-component',
filePath: 'src/my-component.tsx',
slots: [
{ name: '', docs: 'Default slot content' },
{ name: 'header', docs: 'Header slot' },
],
}),
],
typeLibrary: {},
};
const outputTargets: d.OutputTargetDocsCustomElementsManifest[] = [
{ type: 'docs-custom-elements-manifest', file: '/output/custom-elements.json' },
];
await generateCustomElementsManifestDocs(compilerCtx, docsData, outputTargets);
const writtenContent = JSON.parse(writeFileSpy.mock.calls[0][1]);
const declaration = writtenContent.modules[0].declarations[0];
expect(declaration.slots).toHaveLength(2);
expect(declaration.slots[0]).toEqual({ name: '', description: 'Default slot content' });
expect(declaration.slots[1]).toEqual({ name: 'header', description: 'Header slot' });
});
it('includes demos from usage examples', async () => {
const docsData: d.JsonDocs = {
timestamp: 'test',
compiler: { name: '@stencil/core', version: '1.0.0', typescriptVersion: '4.0.0' },
components: [
createMockComponent({
tag: 'my-component',
filePath: 'src/components/my-component/my-component.tsx',
usagesDir: 'src/components/my-component/usage',
usage: {
angular: '```html\n = {}): d.JsonDocsComponent {
return {
dirPath: '',
fileName: 'my-component.tsx',
filePath: 'src/my-component.tsx',
readmePath: 'src/readme.md',
usagesDir: 'src/usage',
tag: 'my-component',
readme: '',
overview: '',
usage: {},
docs: '',
docsTags: [],
encapsulation: 'shadow',
dependents: [],
dependencies: [],
dependencyGraph: {},
props: [],
methods: [],
events: [],
styles: [],
slots: [],
parts: [],
customStates: [],
listeners: [],
...overrides,
};
}
================================================
FILE: src/compiler/docs/test/docs-util.spec.ts
================================================
import { isHexColor, MarkdownTable } from '../../docs/readme/docs-util';
describe('markdown-table', () => {
it('header', () => {
const t = new MarkdownTable();
t.addHeader(['Column 1', 'Column 22', 'Column\n333']);
t.addRow(['Text 1', 'Text 2']);
const o = t.toMarkdown();
expect(o).toEqual([
'| Column 1 | Column 22 | Column 333 |',
'| -------- | --------- | ---------- |',
'| Text 1 | Text 2 | |',
]);
});
it('longest column', () => {
const t = new MarkdownTable();
t.addRow(['Text aa', 'Text b', 'Text c']);
t.addRow(['Text a', 'Text bb', 'Text c']);
t.addRow(['Text a', 'Text bb', 'Text cc']);
const o = t.toMarkdown();
expect(o).toEqual([
'| Text aa | Text b | Text c |',
'| Text a | Text bb | Text c |',
'| Text a | Text bb | Text cc |',
]);
});
it('3 columns', () => {
const t = new MarkdownTable();
t.addRow(['Text 1', 'Text 2', 'Text 3']);
const o = t.toMarkdown();
expect(o).toEqual(['| Text 1 | Text 2 | Text 3 |']);
});
it('one column', () => {
const t = new MarkdownTable();
t.addRow(['Text']);
const o = t.toMarkdown();
expect(o).toEqual(['| Text |']);
});
it('do nothing', () => {
const t = new MarkdownTable();
const o = t.toMarkdown();
expect(o).toEqual([]);
});
});
describe('isHexColor', () => {
it('should return true for valid hex colors', () => {
expect(isHexColor('#FFF')).toBe(true);
expect(isHexColor('#FFFFFF')).toBe(true);
expect(isHexColor('#000000')).toBe(true);
expect(isHexColor('#f0f0f0')).toBe(true);
expect(isHexColor('#aBcDeF')).toBe(true);
});
it('should return false for invalid hex colors', () => {
expect(isHexColor('FFF')).toBe(false);
expect(isHexColor('#GGGGGG')).toBe(false);
expect(isHexColor('#FF')).toBe(false);
expect(isHexColor('#FFFFFFF')).toBe(false);
expect(isHexColor('#FF0000FF')).toBe(false);
});
it('should return false for non-string inputs', () => {
expect(isHexColor('123')).toBe(false);
expect(isHexColor('true')).toBe(false);
expect(isHexColor('{}')).toBe(false);
expect(isHexColor('[]')).toBe(false);
});
});
================================================
FILE: src/compiler/docs/test/generate-doc-data.spec.ts
================================================
import { mockBuildCtx, mockCompilerCtx, mockModule, mockValidatedConfig } from '@stencil/core/testing';
import { DEFAULT_STYLE_MODE, getComponentsFromModules } from '@utils';
import type * as d from '../../../declarations';
import { stubComponentCompilerMeta } from '../../types/tests/ComponentCompilerMeta.stub';
import { AUTO_GENERATE_COMMENT } from '../constants';
import { generateDocData, getDocsStyles } from '../generate-doc-data';
describe('generate-doc-data', () => {
describe('getDocsComponents', () => {
let moduleCmpWithJsdoc: d.Module;
let moduleCmpNoJsdoc: d.Module;
beforeEach(() => {
moduleCmpWithJsdoc = mockModule({
cmps: [
stubComponentCompilerMeta({
docs: {
tags: [],
text: 'This is the overview of `my-component`',
},
}),
],
});
moduleCmpNoJsdoc = mockModule({
cmps: [
stubComponentCompilerMeta({
docs: {
tags: [],
text: '',
},
}),
],
});
});
/**
* Setup function for the {@link generateDocData} function exported by the module under test
* @param moduleMap a map of {@link d.ModuleMap} entities to add to the returned compiler and build contexts
* @returns the arguments required to invoke the method under test
*/
const setup = (
moduleMap: d.ModuleMap,
): { validatedConfig: d.ValidatedConfig; compilerCtx: d.CompilerCtx; buildCtx: d.BuildCtx } => {
const validatedConfig: d.ValidatedConfig = mockValidatedConfig();
const compilerCtx: d.CompilerCtx = mockCompilerCtx(validatedConfig);
compilerCtx.moduleMap = moduleMap;
const modules = Array.from(compilerCtx.moduleMap.values());
const buildCtx: d.BuildCtx = mockBuildCtx(validatedConfig, compilerCtx);
buildCtx.moduleFiles = modules;
buildCtx.components = getComponentsFromModules(modules);
return { validatedConfig, compilerCtx, buildCtx };
};
describe('component JSDoc overview', () => {
it("takes the value from the component's JSDoc", async () => {
const moduleMap: d.ModuleMap = new Map();
moduleMap.set('path/to/component.tsx', moduleCmpWithJsdoc);
const { validatedConfig, compilerCtx, buildCtx } = setup(moduleMap);
const generatedDocData = await generateDocData(validatedConfig, compilerCtx, buildCtx);
expect(generatedDocData.components).toHaveLength(1);
const componentDocData = generatedDocData.components[0];
expect(componentDocData.overview).toBe('This is the overview of `my-component`');
});
it('sets the value to the empty string when there is no JSDoc', async () => {
const moduleMap: d.ModuleMap = new Map();
moduleMap.set('path/to/component.tsx', moduleCmpNoJsdoc);
const { validatedConfig, compilerCtx, buildCtx } = setup(moduleMap);
const generatedDocData = await generateDocData(validatedConfig, compilerCtx, buildCtx);
expect(generatedDocData.components).toHaveLength(1);
const componentDocData = generatedDocData.components[0];
expect(componentDocData.overview).toBe('');
});
});
describe('docs content', () => {
it("sets the field's contents to the jsdoc text if present", async () => {
const moduleMap: d.ModuleMap = new Map();
moduleMap.set('path/to/component.tsx', moduleCmpWithJsdoc);
const { validatedConfig, compilerCtx, buildCtx } = setup(moduleMap);
const generatedDocData = await generateDocData(validatedConfig, compilerCtx, buildCtx);
expect(generatedDocData.components).toHaveLength(1);
const componentDocData = generatedDocData.components[0];
expect(componentDocData.docs).toBe('This is the overview of `my-component`');
});
it("sets the field's contents to an empty string if neither the readme, nor jsdoc are set", async () => {
const moduleMap: d.ModuleMap = new Map();
moduleMap.set('path/to/component.tsx', moduleCmpNoJsdoc);
const { validatedConfig, compilerCtx, buildCtx } = setup(moduleMap);
const generatedDocData = await generateDocData(validatedConfig, compilerCtx, buildCtx);
expect(generatedDocData.components).toHaveLength(1);
const componentDocData = generatedDocData.components[0];
expect(componentDocData.docs).toBe('');
});
it("sets the field's contents to an empty string if the readme doesn't contain the autogenerated comment", async () => {
const moduleMap: d.ModuleMap = new Map();
moduleMap.set('path/to/component.tsx', moduleCmpNoJsdoc);
const { validatedConfig, compilerCtx, buildCtx } = setup(moduleMap);
await compilerCtx.fs.writeFile('readme.md', 'this is manually generated user content');
const generatedDocData = await generateDocData(validatedConfig, compilerCtx, buildCtx);
expect(generatedDocData.components).toHaveLength(1);
const componentDocData = generatedDocData.components[0];
expect(componentDocData.docs).toBe('');
});
it("sets the field's contents to manually generated content when the autogenerated comment is present", async () => {
const moduleMap: d.ModuleMap = new Map();
moduleMap.set('path/to/component.tsx', moduleCmpNoJsdoc);
const { validatedConfig, compilerCtx, buildCtx } = setup(moduleMap);
await compilerCtx.fs.writeFile(
'readme.md',
`this is manually generated user content\n${AUTO_GENERATE_COMMENT}\nauto-generated content`,
);
const generatedDocData = await generateDocData(validatedConfig, compilerCtx, buildCtx);
expect(generatedDocData.components).toHaveLength(1);
const componentDocData = generatedDocData.components[0];
expect(componentDocData.docs).toBe('this is manually generated user content');
});
it("sets the field's contents to a subset of the manually generated content", async () => {
const moduleMap: d.ModuleMap = new Map();
moduleMap.set('path/to/component.tsx', moduleCmpNoJsdoc);
const { validatedConfig, compilerCtx, buildCtx } = setup(moduleMap);
const readmeContent = `
this is manually generated user content
# user header
user content
# another user header
more user content
${AUTO_GENERATE_COMMENT}
#some-header
auto-generated content
`;
await compilerCtx.fs.writeFile('readme.md', readmeContent);
const generatedDocData = await generateDocData(validatedConfig, compilerCtx, buildCtx);
expect(generatedDocData.components).toHaveLength(1);
const componentDocData = generatedDocData.components[0];
expect(componentDocData.docs).toBe('this is manually generated user content');
});
it("sets the field's contents to a an empty string when the manually generated content starts with a '#'", async () => {
const moduleMap: d.ModuleMap = new Map();
moduleMap.set('path/to/component.tsx', moduleCmpNoJsdoc);
const { validatedConfig, compilerCtx, buildCtx } = setup(moduleMap);
const readmeContent = `
# header that leads to skipping
this is manually generated user content
# user header
user content
# another user header
more user content
${AUTO_GENERATE_COMMENT}
#some-header
auto-generated content
`;
await compilerCtx.fs.writeFile('readme.md', readmeContent);
const generatedDocData = await generateDocData(validatedConfig, compilerCtx, buildCtx);
expect(generatedDocData.components).toHaveLength(1);
const componentDocData = generatedDocData.components[0];
expect(componentDocData.docs).toBe('');
});
});
});
describe('getDocsStyles', () => {
it('returns an empty array if no styleDocs exist on the compiler metadata', () => {
const compilerMeta = stubComponentCompilerMeta();
// @ts-ignore - the intent of this test is to verify allocation of a new array if for some reason this is missing
compilerMeta.styleDocs = null;
const actual = getDocsStyles(compilerMeta);
expect(actual).toEqual([]);
});
it('returns an empty array if empty styleDocs exist on the compiler metadata', () => {
const compilerMeta = stubComponentCompilerMeta({ styleDocs: [] });
const actual = getDocsStyles(compilerMeta);
expect(actual).toEqual([]);
});
it("returns a 'sorted' array of one CompilerStyleDoc", () => {
const compilerStyleDoc: d.CompilerStyleDoc = {
annotation: 'prop',
docs: 'these are the docs for this prop',
name: 'my-style-one',
mode: 'md',
};
const compilerMeta = stubComponentCompilerMeta({ styleDocs: [compilerStyleDoc] });
const actual = getDocsStyles(compilerMeta);
expect(actual).toEqual([compilerStyleDoc]);
});
it('returns a sorted array from multiple CompilerStyleDoc', () => {
const compilerStyleDocOne: d.CompilerStyleDoc = {
annotation: 'prop',
docs: 'these are the docs for my-style-a',
name: 'my-style-a',
mode: 'ios',
};
const compilerStyleDocTwo: d.CompilerStyleDoc = {
annotation: 'prop',
docs: 'these are more docs for my-style-b',
name: 'my-style-b',
mode: 'ios',
};
const compilerStyleDocThree: d.CompilerStyleDoc = {
annotation: 'prop',
docs: 'these are more docs for my-style-c',
name: 'my-style-c',
mode: 'ios',
};
const compilerMeta = stubComponentCompilerMeta({
styleDocs: [compilerStyleDocOne, compilerStyleDocThree, compilerStyleDocTwo],
});
const actual = getDocsStyles(compilerMeta);
expect(actual).toEqual([compilerStyleDocOne, compilerStyleDocTwo, compilerStyleDocThree]);
});
it('returns a sorted array from based on mode for the same name', () => {
const mdCompilerStyle: d.CompilerStyleDoc = {
annotation: 'prop',
docs: 'these are the docs for my-style-a',
name: 'my-style-a',
mode: 'md',
};
const iosCompilerStyle: d.CompilerStyleDoc = {
annotation: 'prop',
docs: 'these are the docs for my-style-a',
name: 'my-style-a',
mode: 'ios',
};
const compilerMeta = stubComponentCompilerMeta({
styleDocs: [mdCompilerStyle, iosCompilerStyle],
});
const actual = getDocsStyles(compilerMeta);
expect(actual).toEqual([iosCompilerStyle, mdCompilerStyle]);
});
});
it("returns CompilerStyleDoc with the same name in the order they're provided", () => {
const compilerStyleDocOne: d.CompilerStyleDoc = {
annotation: 'prop',
docs: 'these are the docs for my-style-a (first lowercase)',
name: 'my-style-a',
mode: 'ios',
};
const compilerStyleDocTwo: d.CompilerStyleDoc = {
annotation: 'prop',
docs: 'these are more docs for my-style-A (only capital)',
name: 'my-style-A',
mode: 'ios',
};
const compilerStyleDocThree: d.CompilerStyleDoc = {
annotation: 'prop',
docs: 'these are more docs for my-style-a (second lowercase)',
name: 'my-style-a',
mode: 'ios',
};
const compilerMeta = stubComponentCompilerMeta({
styleDocs: [compilerStyleDocOne, compilerStyleDocThree, compilerStyleDocTwo],
});
const actual = getDocsStyles(compilerMeta);
expect(actual).toEqual([compilerStyleDocOne, compilerStyleDocThree, compilerStyleDocTwo]);
});
describe('default values', () => {
it.each(['', null, undefined])(
"defaults the annotation to an empty string if '%s' is provided",
(annotationValue) => {
const compilerStyleDoc: d.CompilerStyleDoc = {
annotation: 'prop',
docs: 'these are the docs for this prop',
name: 'my-style-one',
mode: DEFAULT_STYLE_MODE,
};
// @ts-ignore the intent of this test to verify the fallback of this field if it's falsy
compilerStyleDoc.annotation = annotationValue;
const compilerMeta = stubComponentCompilerMeta({ styleDocs: [compilerStyleDoc] });
const actual = getDocsStyles(compilerMeta);
expect(actual).toEqual([
{
annotation: '',
docs: 'these are the docs for this prop',
name: 'my-style-one',
},
]);
},
);
it.each(['', null, undefined])("defaults the docs to an empty string if '%s' is provided", (docsValue) => {
const compilerStyleDoc: d.CompilerStyleDoc = {
annotation: 'prop',
docs: 'these are the docs for this prop',
name: 'my-style-one',
mode: DEFAULT_STYLE_MODE,
};
// @ts-ignore the intent of this test to verify the fallback of this field if it's falsy
compilerStyleDoc.docs = docsValue;
const compilerMeta = stubComponentCompilerMeta({ styleDocs: [compilerStyleDoc] });
const actual = getDocsStyles(compilerMeta);
expect(actual).toEqual([
{
annotation: 'prop',
docs: '',
name: 'my-style-one',
},
]);
});
it.each(['', undefined, null, DEFAULT_STYLE_MODE])(
"uses 'undefined' for the mode value when '%s' is provided",
(modeValue) => {
const compilerStyleDoc: d.CompilerStyleDoc = {
annotation: 'prop',
docs: 'these are the docs for this prop',
name: 'my-style-one',
// we intentionally set this to non-compliant types for the purpose of this test, hence the type assertion
mode: modeValue as unknown as string,
};
const compilerMeta = stubComponentCompilerMeta({ styleDocs: [compilerStyleDoc] });
const actual = getDocsStyles(compilerMeta);
expect(actual).toEqual([
{
annotation: 'prop',
docs: 'these are the docs for this prop',
name: 'my-style-one',
mode: undefined,
},
]);
},
);
it('uses the mode value, when a valid string is provided', () => {
const compilerStyleDoc: d.CompilerStyleDoc = {
annotation: 'prop',
docs: 'these are the docs for this prop',
name: 'my-style-one',
mode: 'valid-string',
};
const compilerMeta = stubComponentCompilerMeta({ styleDocs: [compilerStyleDoc] });
const actual = getDocsStyles(compilerMeta);
expect(actual).toEqual([
{
annotation: 'prop',
docs: 'these are the docs for this prop',
name: 'my-style-one',
mode: 'valid-string',
},
]);
});
});
});
================================================
FILE: src/compiler/docs/test/markdown-dependencies.spec.ts
================================================
import type * as d from '../../../declarations';
import { DEFAULT_TARGET_COMPONENT_STYLES } from '../../config/constants';
import { depsToMarkdown } from '../readme/markdown-dependencies';
describe('depsToMarkdown()', () => {
it('should use default settings if docs.markdown configuration was not provided', () => {
const mockConfig = {
docs: {
markdown: {
targetComponent: {
...DEFAULT_TARGET_COMPONENT_STYLES,
},
},
},
} as d.ValidatedConfig;
const md = depsToMarkdown(
{
dependencies: [],
dependencyGraph: {
's-test': ['s-test-dep1'],
},
dependents: [],
docs: '',
docsTags: [],
encapsulation: undefined,
events: [],
listeners: [],
methods: [],
parts: [],
customStates: [],
props: [],
readme: '',
slots: [],
styles: [],
tag: '',
usage: undefined,
},
[],
mockConfig,
);
expect(md).toEqual([
'## Dependencies',
'',
'### Graph',
'```mermaid',
'graph TD;',
' s-test --> s-test-dep1',
` style fill:${DEFAULT_TARGET_COMPONENT_STYLES.background},stroke:${DEFAULT_TARGET_COMPONENT_STYLES.textColor},stroke-width:4px`,
'```',
'',
]);
});
it('should use provided background settings for generated dependencies graph', () => {
const mockColor = '#445334';
const mockConfig = {
docs: {
markdown: {
targetComponent: {
background: mockColor,
textColor: DEFAULT_TARGET_COMPONENT_STYLES.textColor,
},
},
},
} as d.ValidatedConfig;
const md = depsToMarkdown(
{
dependencies: [],
dependencyGraph: {
's-test': ['s-test-dep1'],
},
dependents: [],
docs: '',
docsTags: [],
encapsulation: undefined,
events: [],
listeners: [],
methods: [],
parts: [],
customStates: [],
props: [],
readme: '',
slots: [],
styles: [],
tag: '',
usage: undefined,
},
[],
mockConfig,
);
expect(md).toEqual([
'## Dependencies',
'',
'### Graph',
'```mermaid',
'graph TD;',
' s-test --> s-test-dep1',
` style fill:${mockColor},stroke:${DEFAULT_TARGET_COMPONENT_STYLES.textColor},stroke-width:4px`,
'```',
'',
]);
});
it('should use provided text color settings for generated dependencies graph', () => {
const mockColor = '#445334';
const mockConfig = {
docs: {
markdown: {
targetComponent: {
background: DEFAULT_TARGET_COMPONENT_STYLES.background,
textColor: mockColor,
},
},
},
} as d.ValidatedConfig;
const md = depsToMarkdown(
{
dependencies: [],
dependencyGraph: {
's-test': ['s-test-dep1'],
},
dependents: [],
docs: '',
docsTags: [],
encapsulation: undefined,
events: [],
listeners: [],
methods: [],
parts: [],
customStates: [],
props: [],
readme: '',
slots: [],
styles: [],
tag: '',
usage: undefined,
},
[],
mockConfig,
);
expect(md).toEqual([
'## Dependencies',
'',
'### Graph',
'```mermaid',
'graph TD;',
' s-test --> s-test-dep1',
` style fill:${DEFAULT_TARGET_COMPONENT_STYLES.background},stroke:${mockColor},stroke-width:4px`,
'```',
'',
]);
});
});
================================================
FILE: src/compiler/docs/test/markdown-overview.spec.ts
================================================
import { overviewToMarkdown } from '../readme/markdown-overview';
describe('markdown-overview', () => {
describe('overviewToMarkdown', () => {
it('returns no overview if no docs exist', () => {
const generatedOverview = overviewToMarkdown('').join('\n');
expect(generatedOverview).toBe('');
});
it('generates a single line overview', () => {
const generatedOverview = overviewToMarkdown('This is a custom button component').join('\n');
expect(generatedOverview).toBe(`## Overview
This is a custom button component
`);
});
it('generates a multi-line overview', () => {
const description = `This is a custom button component.
It is to be used throughout the design system.
This is a comment followed by a newline.
`;
const generatedOverview = overviewToMarkdown(description).join('\n');
expect(generatedOverview).toBe(`## Overview
This is a custom button component.
It is to be used throughout the design system.
This is a comment followed by a newline.
`);
});
it('trims all leading newlines & leaves one at the end', () => {
const description = `
This is a custom button component.
`;
const generatedOverview = overviewToMarkdown(description).join('\n');
expect(generatedOverview).toBe(`## Overview
This is a custom button component.
`);
});
});
});
================================================
FILE: src/compiler/docs/test/markdown-props.spec.ts
================================================
import { propsToMarkdown } from '../../docs/readme/markdown-props';
describe('markdown props', () => {
it('advanced union types', () => {
const markdown = propsToMarkdown([
{
name: 'hello',
attr: 'hello',
docs: 'This is a prop',
default: 'false',
type: 'boolean | string',
mutable: false,
optional: false,
required: false,
reflectToAttr: false,
docsTags: [],
values: [],
getter: false,
setter: false,
},
{
name: 'hello',
attr: undefined,
docs: 'This is a prop',
default: 'false',
type: 'boolean | string',
mutable: false,
optional: false,
required: false,
reflectToAttr: false,
docsTags: [],
values: [],
getter: false,
setter: false,
},
]).join('\n');
expect(markdown).toEqual(`## Properties
| Property | Attribute | Description | Type | Default |
| -------- | --------- | -------------- | ------------------- | ------- |
| \`hello\` | \`hello\` | This is a prop | \`boolean \\| string\` | \`false\` |
| \`hello\` | -- | This is a prop | \`boolean \\| string\` | \`false\` |
`);
});
it('escapes template literal types', () => {
const markdown = propsToMarkdown([
{
name: 'width',
attr: 'width',
docs: 'Width of the button',
default: 'undefined',
type: '`${number}px` | `${number}%`',
mutable: false,
optional: false,
required: false,
reflectToAttr: false,
docsTags: [],
values: [],
getter: false,
setter: false,
},
]).join('\n');
expect(markdown).toEqual(`## Properties
| Property | Attribute | Description | Type | Default |
| -------- | --------- | ------------------- | ----------------------------------- | ----------- |
| \`width\` | \`width\` | Width of the button | \`\` \`\${number}px\` \\| \`\${number}%\` \`\` | \`undefined\` |
`);
});
it('escapes backticks in default value', () => {
const markdown = propsToMarkdown([
{
name: 'quote',
attr: 'quote',
docs: 'Quote character',
default: "'`'",
type: 'string',
mutable: false,
optional: false,
required: false,
reflectToAttr: false,
docsTags: [],
values: [],
getter: false,
setter: false,
},
]).join('\n');
expect(markdown).toEqual(`## Properties
| Property | Attribute | Description | Type | Default |
| -------- | --------- | --------------- | -------- | --------- |
| \`quote\` | \`quote\` | Quote character | \`string\` | \`\` '\`' \`\` |
`);
});
it('outputs `undefined` in default column when `prop.default` is undefined', () => {
const markdown = propsToMarkdown([
{
name: 'first',
attr: 'first',
docs: 'First name',
default: undefined,
type: 'string',
mutable: false,
optional: false,
required: false,
reflectToAttr: false,
docsTags: [],
values: [],
getter: false,
setter: false,
},
]).join('\n');
expect(markdown).toBe(`## Properties
| Property | Attribute | Description | Type | Default |
| -------- | --------- | ----------- | -------- | ----------- |
| \`first\` | \`first\` | First name | \`string\` | \`undefined\` |
`);
});
});
================================================
FILE: src/compiler/docs/test/output-docs.spec.ts
================================================
import type * as d from '../../../declarations';
import { generateMarkdown } from '../readme/output-docs';
describe('css-props to markdown', () => {
describe('generateMarkdown', () => {
const mockReadmeOutput: d.OutputTargetDocsReadme = {
type: 'docs-readme',
footer: '*Built with StencilJS*',
};
const mockComponent: d.JsonDocsComponent = {
tag: 'my-component',
filePath: 'src/components/my-component/my-component.tsx',
fileName: 'my-component.tsx',
dirPath: 'src/components/my-component',
readmePath: 'src/components/my-component/readme.md',
usagesDir: 'src/components/my-component/usage',
encapsulation: 'shadow',
docs: '',
docsTags: [],
usage: {},
props: [],
methods: [],
events: [],
listeners: [],
styles: [],
slots: [],
parts: [],
dependents: [],
dependencies: [],
dependencyGraph: {},
customStates: [],
readme: '',
};
it.each([
{
name: 'component styles when available',
componentStyles: [
{ name: '--background', docs: 'Background color', annotation: 'prop' as const, mode: undefined },
{ name: '--color', docs: 'Text color', annotation: 'prop' as const, mode: undefined },
],
shouldContain: ['## CSS Custom Properties', '`--background`', 'Background color', '`--color`', 'Text color'],
shouldNotContain: [],
},
{
name: 'preserved CSS props (already in component.styles)',
componentStyles: [
{
name: '--bg',
docs: 'Defaults to var(--nano-color-blue-cerulean-1000);',
annotation: 'prop' as const,
mode: undefined,
},
{ name: '--text-color', docs: 'Text color of the component', annotation: 'prop' as const, mode: undefined },
],
shouldContain: ['## CSS Custom Properties', '`--bg`', 'Defaults to var(--nano-color-blue-cerulean-1000);'],
shouldNotContain: [],
},
{
name: 'no CSS section when styles are empty',
componentStyles: [],
shouldContain: [],
shouldNotContain: ['## CSS Custom Properties'],
},
{
name: 'updated component styles',
componentStyles: [
{ name: '--new-prop', docs: 'New property from build', annotation: 'prop' as const, mode: undefined },
],
shouldContain: ['`--new-prop`', 'New property from build'],
shouldNotContain: [],
},
])('should use $name', ({ componentStyles, shouldContain, shouldNotContain }) => {
const component: d.JsonDocsComponent = {
...mockComponent,
styles: componentStyles,
};
const markdown = generateMarkdown('# my-component', component, [], mockReadmeOutput);
shouldContain.forEach((expected) => {
expect(markdown).toContain(expected);
});
shouldNotContain.forEach((unexpected) => {
expect(markdown).not.toContain(unexpected);
});
});
it('should escape special characters in CSS prop descriptions', () => {
const component: d.JsonDocsComponent = {
...mockComponent,
styles: [
{
name: '--bg',
docs: 'Defaults to var(--nano-color-blue-cerulean-1000); with | pipes',
annotation: 'prop',
mode: undefined,
},
],
};
const markdown = generateMarkdown('# my-component', component, [], mockReadmeOutput);
// Pipe characters are escaped in markdown tables
expect(markdown).toContain('Defaults to var(--nano-color-blue-cerulean-1000); with \\| pipes');
});
});
});
================================================
FILE: src/compiler/docs/test/style-docs.spec.ts
================================================
import type * as d from '@stencil/core/declarations';
import { DEFAULT_STYLE_MODE } from '@utils';
import { parseStyleDocs } from '../style-docs';
describe('style-docs', () => {
let styleDocs: d.StyleDoc[];
beforeEach(() => {
styleDocs = [];
});
it('no docs', () => {
const styleText = `
/**
* @prop --max-width
*/
body {
color: red;
}
`;
parseStyleDocs(styleDocs, styleText);
expect(styleDocs).toEqual([{ name: `--max-width`, docs: ``, annotation: 'prop' }]);
});
it('multiline', () => {
const styleText = `
/**
* @prop --color: This is the docs
* for color.
@prop --background : This is the docs
for background. It is two
* sentences and some :: man.
*/
body {
color: red;
}
`;
parseStyleDocs(styleDocs, styleText);
expect(styleDocs).toEqual([
{ name: `--color`, docs: `This is the docs for color.`, annotation: 'prop' },
{
name: `--background`,
docs: `This is the docs for background. It is two sentences and some :: man.`,
annotation: 'prop',
},
]);
});
it('docs', () => {
const styleText = `
/**
* @prop --max-width: Max width of the alert
* @prop --color: Descript with : in it
* * @prop --background: background docs
@prop --font-weight: font-weight docs
*/
html {
height: 100%;
}
/**
* @prop --border: border docs
* @prop --font-size: font-size docs
*/
/** @prop --padding: padding docs */
body {
color: red;
}
`;
parseStyleDocs(styleDocs, styleText);
expect(styleDocs).toEqual([
{ name: `--max-width`, docs: `Max width of the alert`, annotation: 'prop' },
{ name: `--color`, docs: `Descript with : in it`, annotation: 'prop' },
{ name: `--background`, docs: `background docs`, annotation: 'prop' },
{ name: `--font-weight`, docs: `font-weight docs`, annotation: 'prop' },
{ name: `--border`, docs: `border docs`, annotation: 'prop' },
{ name: `--font-size`, docs: `font-size docs`, annotation: 'prop' },
{ name: `--padding`, docs: `padding docs`, annotation: 'prop' },
]);
});
it('invalid css prop comment', () => {
const styleText = `
/**
* hello
* @prop max-width: Max width of the alert
* --max-width: Max width of the alert
*/
/*
* @prop --max-width
*/
/* hi i'm normal comments */
body {
color: red;
}
`;
parseStyleDocs(styleDocs, styleText);
expect(styleDocs).toEqual([]);
});
it('no closing comments', () => {
const styleText = `
/**
body {
color: red;
}
`;
parseStyleDocs(styleDocs, styleText);
expect(styleDocs).toEqual([]);
});
it('no comments', () => {
const styleText = `
body {
color: red;
}
`;
parseStyleDocs(styleDocs, styleText);
expect(styleDocs).toEqual([]);
});
it('empty styleText', () => {
const styleText = ``;
parseStyleDocs(styleDocs, styleText);
expect(styleDocs).toEqual([]);
});
it('null styleText', () => {
const styleText: null = null;
parseStyleDocs(styleDocs, styleText);
expect(styleDocs).toEqual([]);
});
it('works with sass loud comments', () => {
const styleText = `
/*!
* @prop --max-width: Max width of the alert
*/
body {
color: red;
}
`;
parseStyleDocs(styleDocs, styleText);
expect(styleDocs).toEqual([{ name: `--max-width`, docs: `Max width of the alert`, annotation: 'prop' }]);
});
it('works with multiple, mixed comment types', () => {
const styleText = `
/**
* @prop --max-width: Max width of the alert
*/
/*!
* @prop --max-width-loud: Max width of the alert (loud)
*/
body {
color: red;
}
`;
parseStyleDocs(styleDocs, styleText);
expect(styleDocs).toEqual([
{ name: `--max-width`, docs: `Max width of the alert`, annotation: 'prop' },
{ name: `--max-width-loud`, docs: `Max width of the alert (loud)`, annotation: 'prop' },
]);
});
it.each(['ios', 'md', undefined, '', DEFAULT_STYLE_MODE])("attaches mode metadata for a style mode '%s'", (mode) => {
const styleText = `
/*!
* @prop --max-width: Max width of the alert
*/
body {
color: red;
}
`;
parseStyleDocs(styleDocs, styleText, mode);
expect(styleDocs).toEqual([{ name: `--max-width`, docs: `Max width of the alert`, annotation: 'prop', mode }]);
});
});
================================================
FILE: src/compiler/docs/test/tsconfig.json
================================================
{
"extends": "../../../testing/tsconfig.internal.json"
}
================================================
FILE: src/compiler/docs/vscode/index.ts
================================================
import { isOutputTargetDocsVscode, join } from '@utils';
import type * as d from '../../../declarations';
import { getNameText } from '../generate-doc-data';
/**
* Generate [custom data](https://github.com/microsoft/vscode-custom-data) to augment existing HTML types in VS Code.
* This function writes the custom data as a JSON file to disk, which can be used in VS Code to inform the IDE about
* custom elements generated by Stencil.
*
* The JSON generated by this function must conform to the
* [HTML custom data schema](https://github.com/microsoft/vscode-html-languageservice/blob/e7ae8a7170df5e721a13cee1b86e293b24eb3b20/docs/customData.schema.json).
*
* This function generates custom data for HTML only at this time (it does not generate custom data for CSS).
*
* @param compilerCtx the current compiler context
* @param docsData an intermediate representation documentation derived from compiled Stencil components
* @param outputTargets the output target(s) the associated with the current build
*/
export const generateVscodeDocs = async (
compilerCtx: d.CompilerCtx,
docsData: d.JsonDocs,
outputTargets: d.OutputTarget[],
): Promise => {
const vsCodeOutputTargets = outputTargets.filter(isOutputTargetDocsVscode);
if (vsCodeOutputTargets.length === 0) {
return;
}
await Promise.all(
vsCodeOutputTargets.map(async (outputTarget: d.OutputTargetDocsVscode): Promise => {
const json = {
/**
* the 'version' top-level field is required by the schema. changes to the JSON generated by Stencil must:
* - comply with v1.X of the schema _OR_
* - increment this field as a part of updating the JSON generation. This should be considered a breaking change
*
* {@link https://github.com/microsoft/vscode-html-languageservice/blob/e7ae8a7170df5e721a13cee1b86e293b24eb3b20/src/htmlLanguageTypes.ts#L184}
*/
version: 1.1,
tags: docsData.components.map((cmp: d.JsonDocsComponent) => ({
name: cmp.tag,
description: {
kind: 'markdown',
value: cmp.docs,
},
attributes: cmp.props
.filter((p: d.JsonDocsProp): p is DocPropWithAttribute => p.attr !== undefined && p.attr.length > 0)
.map(serializeAttribute),
references: getReferences(cmp, outputTarget.sourceCodeBaseUrl),
})),
};
// fields in the custom data may have a value of `undefined`. calling `stringify` will remove such fields.
const jsonContent = JSON.stringify(json, null, 2);
await compilerCtx.fs.writeFile(outputTarget.file, jsonContent);
}),
);
};
/**
* This type describes external references for a custom element.
*
* An internal representation of Microsoft/VS Code's [`IReference` type](https://github.com/microsoft/vscode-html-languageservice/blob/e7ae8a7170df5e721a13cee1b86e293b24eb3b20/src/htmlLanguageTypes.ts#L153).
*/
type TagReference = {
name: string;
url: string;
};
/**
* Generate a 'references' section for a component's documentation.
* @param cmp the Stencil component to generate a references section for
* @param repoBaseUrl an optional URL, that when provided, will add a reference to the source code for the component
* @returns the generated references section, or undefined if no references could be generated
*/
const getReferences = (cmp: d.JsonDocsComponent, repoBaseUrl: string | undefined): TagReference[] | undefined => {
// collect any `@reference` JSDoc tags on the component
const references = getNameText('reference', cmp.docsTags).map(([name, url]) => ({ name, url }));
if (repoBaseUrl) {
references.push({
name: 'Source code',
url: join(repoBaseUrl, cmp.filePath ?? ''),
});
}
if (references.length > 0) {
return references;
}
return undefined;
};
/**
* A type that describes the attributes that can be used with a custom element.
*
* An internal representation of Microsoft/VS Code's [`IAttributeData` type](https://github.com/microsoft/vscode-html-languageservice/blob/e7ae8a7170df5e721a13cee1b86e293b24eb3b20/src/htmlLanguageTypes.ts#L165).
*/
type AttributeData = {
name: string;
description: string;
values?: { name: string }[];
};
/**
* Utility that provides a type-safe way of making a key K on a type T required.
*
* This is preferable than using an intersection of `T & {K: someType}` as it ensures that:
* - the type of K will always match the type T[K]
* - it should error should K not exist in `keyof T`
*/
type WithRequired