product-doc 0.13.2 → 0.14.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +31 -22
- package/guide/previews.md +64 -0
- package/guide/ui.md +13 -0
- package/guide.md +20 -17
- package/lib/changes.d.ts +4 -0
- package/lib/changes.js +5 -0
- package/lib/cli.js +99 -12
- package/lib/diffmapConfig.d.ts +41 -0
- package/lib/diffmapConfig.js +71 -0
- package/lib/git.d.ts +9 -4
- package/lib/git.js +42 -7
- package/lib/github/route.d.ts +1 -0
- package/lib/github/route.js +14 -5
- package/lib/parseFence.d.ts +30 -0
- package/lib/parseFence.js +62 -0
- package/lib/parseViewer.js +15 -0
- package/lib/preview/PreviewRoute.d.ts +20 -0
- package/lib/preview/PreviewRoute.js +279 -0
- package/lib/preview/index.d.ts +3 -0
- package/lib/preview/index.js +2 -0
- package/lib/preview/protocol.d.ts +85 -0
- package/lib/preview/protocol.js +114 -0
- package/lib/readDiffmapConfig.d.ts +12 -0
- package/lib/readDiffmapConfig.js +25 -0
- package/lib/serve.d.ts +2 -0
- package/lib/serve.js +41 -7
- package/lib/share.js +5 -1
- package/package.json +21 -4
- package/viewer-dist/assets/angular-html-C4LeXCe-.js +1 -0
- package/viewer-dist/assets/angular-ts-CRxW7p1W.js +1 -0
- package/viewer-dist/assets/{apl-Dio8Ke0X.js → apl-D60kkz--.js} +1 -1
- package/viewer-dist/assets/astro-3Zgg9XqN.js +1 -0
- package/viewer-dist/assets/{bat-HFWzIrao.js → bat-qdxAdBWQ.js} +1 -1
- package/viewer-dist/assets/{bibtex-Conh3HYz.js → bibtex-Ci_nEsc7.js} +1 -1
- package/viewer-dist/assets/blade-B5YUZNEG.js +1 -0
- package/viewer-dist/assets/bsl-_VjlB9mv.js +1 -0
- package/viewer-dist/assets/c-BNQJhXlP.js +1 -0
- package/viewer-dist/assets/cairo-DLTphjLi.js +1 -0
- package/viewer-dist/assets/{chapel-C1sUNn9S.js → chapel-CFMD-Djs.js} +1 -1
- package/viewer-dist/assets/{clojure-zIjcJonk.js → clojure-DqKBuwfJ.js} +1 -1
- package/viewer-dist/assets/{cmake-T_kMSWuN.js → cmake-Bj61d0ZC.js} +1 -1
- package/viewer-dist/assets/{cobol-BvqUwMCV.js → cobol-DY6IFdmX.js} +1 -1
- package/viewer-dist/assets/{coffee-BSYIIMkB.js → coffee-BP03ytLP.js} +1 -1
- package/viewer-dist/assets/{core-A38CGsfQ.js → core-BkcJpkJE.js} +2 -2
- package/viewer-dist/assets/cpp-CUBNVKxn.js +1 -0
- package/viewer-dist/assets/{crystal-D0XIDmeW.js → crystal-NSr8mDkd.js} +1 -1
- package/viewer-dist/assets/{csharp-B3DbjJyj.js → csharp-dmMxLVLW.js} +1 -1
- package/viewer-dist/assets/css-BiJUKRHp.js +1 -0
- package/viewer-dist/assets/{csv-B_R7vXwK.js → csv-Dx-8-gkx.js} +1 -1
- package/viewer-dist/assets/{dart-_dH3dQdM.js → dart-CHZY9Xhz.js} +1 -1
- package/viewer-dist/assets/{diff-CR4ZX0DC.js → diff-woXpYk--.js} +1 -1
- package/viewer-dist/assets/{docker-CAzcIhYn.js → docker-IyjqRm3v.js} +1 -1
- package/viewer-dist/assets/edge-DznSXZdq.js +1 -0
- package/viewer-dist/assets/{elixir-BL8v4QDr.js → elixir-D1HcpP2u.js} +1 -1
- package/viewer-dist/assets/{elm-CC1TmzeR.js → elm-Bmx6Fs0i.js} +1 -1
- package/viewer-dist/assets/{erb-CHbMJpQy.js → erb-CdvLbCTI.js} +1 -1
- package/viewer-dist/assets/erlang-Cphh6RMH.js +1 -0
- package/viewer-dist/assets/fortran-fixed-form-DEKoE2YW.js +1 -0
- package/viewer-dist/assets/{fortran-free-form-uHOymLAb.js → fortran-free-form-CYNrtFtB.js} +1 -1
- package/viewer-dist/assets/fsharp-D13ZGOAj.js +1 -0
- package/viewer-dist/assets/gdresource-xMC7jr7x.js +1 -0
- package/viewer-dist/assets/{gdscript-DJFPOtzS.js → gdscript-DYvRD3hg.js} +1 -1
- package/viewer-dist/assets/{gdshader-kiBtQlv1.js → gdshader-CBce3t8t.js} +1 -1
- package/viewer-dist/assets/git-commit-BSykSTBG.js +1 -0
- package/viewer-dist/assets/{git-rebase-Bh7mDoAc.js → git-rebase-C-RR1FSc.js} +1 -1
- package/viewer-dist/assets/{glimmer-js-CIdbWayl.js → glimmer-js-BUse42ki.js} +1 -1
- package/viewer-dist/assets/{glimmer-ts-B16xCo2k.js → glimmer-ts-zH_nSjyx.js} +1 -1
- package/viewer-dist/assets/glsl-CyFpZtQv.js +1 -0
- package/viewer-dist/assets/{go-CFMhVTkq.js → go-rLFTqkRN.js} +1 -1
- package/viewer-dist/assets/graphql-BIyAKkG2.js +1 -0
- package/viewer-dist/assets/{groovy-Dj7WCBJM.js → groovy-CacY0gHj.js} +1 -1
- package/viewer-dist/assets/{hack-C30D-q0p.js → hack-qk6BiceN.js} +1 -1
- package/viewer-dist/assets/haml-BkBm6IgF.js +1 -0
- package/viewer-dist/assets/{handlebars-g-3gLrXt.js → handlebars-FMeV8O-Z.js} +1 -1
- package/viewer-dist/assets/{haxe-CD8O8Ul0.js → haxe-C8oCnwJJ.js} +1 -1
- package/viewer-dist/assets/{highlights-B57wCzB5.js → highlights-NUSPeu9U.js} +2 -2
- package/viewer-dist/assets/{hlsl-ajL2FB-w.js → hlsl-Cvrh5tZx.js} +1 -1
- package/viewer-dist/assets/html-CvoVzlT3.js +1 -0
- package/viewer-dist/assets/{html-derivative-DyzJkWO6.js → html-derivative-CmO0_REm.js} +1 -1
- package/viewer-dist/assets/{http-BjrBtiM6.js → http-c4_vT9ST.js} +1 -1
- package/viewer-dist/assets/{hurl-B4P9s9G3.js → hurl-BqZA9I9Q.js} +1 -1
- package/viewer-dist/assets/hxml-Dcm88srW.js +1 -0
- package/viewer-dist/assets/index-C8Oxwcs8.js +264 -0
- package/viewer-dist/assets/{ini-0B7NLFlx.js → ini-B5eOa1yu.js} +1 -1
- package/viewer-dist/assets/java-D7h0NA_A.js +1 -0
- package/viewer-dist/assets/javascript-DcMHgNcu.js +1 -0
- package/viewer-dist/assets/{jinja-dRcm23Ea.js → jinja-IxhZJXij.js} +1 -1
- package/viewer-dist/assets/{jison-D3aJooqo.js → jison-Ru_S5AEn.js} +1 -1
- package/viewer-dist/assets/json-DePJdKYk.js +1 -0
- package/viewer-dist/assets/{jsonc-dcnCvL0G.js → jsonc-CYpm1nAK.js} +1 -1
- package/viewer-dist/assets/jsx-BUUYi3qs.js +1 -0
- package/viewer-dist/assets/julia-BuaSHoYZ.js +1 -0
- package/viewer-dist/assets/just-BJW1YJYB.js +1 -0
- package/viewer-dist/assets/langs-Di6vPLUk.js +2 -0
- package/viewer-dist/assets/{latex-B_Ztlc7G.js → latex-B6yY1rfM.js} +1 -1
- package/viewer-dist/assets/{less-B64L-FWb.js → less-DVTAwKKz.js} +1 -1
- package/viewer-dist/assets/{liquid-CQNtsgCr.js → liquid-DNgNMjPq.js} +1 -1
- package/viewer-dist/assets/loader-Cvp9wZb2.js +1 -0
- package/viewer-dist/assets/{log-BvtJ4bSl.js → log-BNLmms1o.js} +1 -1
- package/viewer-dist/assets/lua-Z49wBRLR.js +1 -0
- package/viewer-dist/assets/{make-URElk0GJ.js → make-Dixweg8N.js} +1 -1
- package/viewer-dist/assets/{markdown-CboqBxpY.js → markdown-BYOwaDjH.js} +1 -1
- package/viewer-dist/assets/marko-i5cBncq8.js +1 -0
- package/viewer-dist/assets/mdc-C3wRYKz5.js +1 -0
- package/viewer-dist/assets/nextflow-CSgcYZcx.js +1 -0
- package/viewer-dist/assets/{nextflow-groovy-C770ykRh.js → nextflow-groovy-D7IRt6Pp.js} +1 -1
- package/viewer-dist/assets/{nginx-BxRBJ-Af.js → nginx-BrbrEdla.js} +1 -1
- package/viewer-dist/assets/nim-BCe7ZKXY.js +1 -0
- package/viewer-dist/assets/{objective-c-D_ECFp-D.js → objective-c-D1A_Heim.js} +1 -1
- package/viewer-dist/assets/{ocaml-D6dNsUd0.js → ocaml-O90oeIOV.js} +1 -1
- package/viewer-dist/assets/org-DDCXkPsd.js +1 -0
- package/viewer-dist/assets/{perl-sgZsTtaf.js → perl-DLhC7S_Q.js} +1 -1
- package/viewer-dist/assets/{php-D9QpVhjP.js → php-CDzTReqR.js} +1 -1
- package/viewer-dist/assets/{postcss-D_Wz94rJ.js → postcss-BXeXVLqQ.js} +1 -1
- package/viewer-dist/assets/{powershell-CItYMEtV.js → powershell-QtSnmXcu.js} +1 -1
- package/viewer-dist/assets/{pug-nGRwXpob.js → pug-COoI2o4U.js} +1 -1
- package/viewer-dist/assets/{python-CzFU0dpx.js → python-gzcpVVnB.js} +1 -1
- package/viewer-dist/assets/{qml-BxleM7bJ.js → qml-g4UDed-8.js} +1 -1
- package/viewer-dist/assets/r-CvCSiWB_.js +1 -0
- package/viewer-dist/assets/{raku-BtFKomnU.js → raku-B3gFvitq.js} +1 -1
- package/viewer-dist/assets/{razor-UAq-8THt.js → razor-BRLDaw7i.js} +1 -1
- package/viewer-dist/assets/regexp-I2jnduhj.js +1 -0
- package/viewer-dist/assets/rst-BEQnCgL0.js +1 -0
- package/viewer-dist/assets/{ruby-B6sU6EpJ.js → ruby-COXzLN2W.js} +1 -1
- package/viewer-dist/assets/{rust-DBZE5Si3.js → rust-DpiIf5JO.js} +1 -1
- package/viewer-dist/assets/{sas-BowjnAvi.js → sas-Cr47JhdL.js} +1 -1
- package/viewer-dist/assets/{scala-o2NiCLJc.js → scala-BiFt_7mu.js} +1 -1
- package/viewer-dist/assets/scss-BuNb6cgZ.js +1 -0
- package/viewer-dist/assets/{sdbl-CpzYUp7e.js → sdbl-bTVj8UrX.js} +1 -1
- package/viewer-dist/assets/shaderlab-TOUzSsQk.js +1 -0
- package/viewer-dist/assets/shellscript-B51zB43X.js +1 -0
- package/viewer-dist/assets/{shellsession-DDrivR0a.js → shellsession-B-KBpmJs.js} +1 -1
- package/viewer-dist/assets/shiki-CTIyHrkn.js +2 -0
- package/viewer-dist/assets/{soy-CUUUw2U6.js → soy-B-X4e_cm.js} +1 -1
- package/viewer-dist/assets/sparql-D_iOobhT.js +1 -0
- package/viewer-dist/assets/sql-CrePkbX5.js +1 -0
- package/viewer-dist/assets/{stata-Dj4sbAEx.js → stata-LQMPNdRb.js} +1 -1
- package/viewer-dist/assets/{stream-tokenizer-a_hv0fYK.js → stream-tokenizer-8imCpDcl.js} +2 -2
- package/viewer-dist/assets/{stylus-LiTfbrWi.js → stylus-B6D30XZt.js} +1 -1
- package/viewer-dist/assets/{surrealql-NoXzmj18.js → surrealql-DalIYx4r.js} +1 -1
- package/viewer-dist/assets/svelte-CutSaB0m.js +1 -0
- package/viewer-dist/assets/{swift-DQ24oLw9.js → swift-CyEgAFGc.js} +1 -1
- package/viewer-dist/assets/{system-verilog-Dp2k_mze.js → system-verilog-Dh5ihWbf.js} +1 -1
- package/viewer-dist/assets/templ-STIZV9cS.js +1 -0
- package/viewer-dist/assets/tex-JPaUWOrn.js +1 -0
- package/viewer-dist/assets/themes-CGzFOfgV.js +2 -0
- package/viewer-dist/assets/{ts-tags-DLz2GTd3.js → ts-tags-DugY2c1f.js} +1 -1
- package/viewer-dist/assets/tsx-DvWhG4dC.js +1 -0
- package/viewer-dist/assets/{turtle-CcN57yC0.js → turtle-ByJddavk.js} +1 -1
- package/viewer-dist/assets/twig-CAQ2meH1.js +1 -0
- package/viewer-dist/assets/typescript-BTGs5etX.js +1 -0
- package/viewer-dist/assets/typst-D2auzO0m.js +1 -0
- package/viewer-dist/assets/{vb-3nVziYZS.js → vb-DOwzaHZ0.js} +1 -1
- package/viewer-dist/assets/{verilog-kL8Dwv27.js → verilog-B2gwz-sJ.js} +1 -1
- package/viewer-dist/assets/vue-Bu9nv_eN.js +1 -0
- package/viewer-dist/assets/{vue-html-CGMs_6qn.js → vue-html-BXjKVtKk.js} +1 -1
- package/viewer-dist/assets/vue-vine-Ci2qndh_.js +1 -0
- package/viewer-dist/assets/xml-C01ajBW7.js +1 -0
- package/viewer-dist/assets/{xsl-Czhm44Ae.js → xsl-CCLNyvR3.js} +1 -1
- package/viewer-dist/assets/yaml-BWCS3NLV.js +1 -0
- package/viewer-dist/assets/{zig-B7sSDI6F.js → zig-CMLA9XwU.js} +1 -1
- package/viewer-dist/index.html +1 -7
- package/viewer-dist/assets/angular-html-BswFT_28.js +0 -1
- package/viewer-dist/assets/angular-html-Cwa-lTMy.js +0 -1
- package/viewer-dist/assets/angular-ts-DOMhGxLQ.js +0 -1
- package/viewer-dist/assets/appendItems-BRdTC5zu.js +0 -3
- package/viewer-dist/assets/astro-CN6YWUG3.js +0 -1
- package/viewer-dist/assets/bat-Di-EdOIU.js +0 -1
- package/viewer-dist/assets/bibtex-CimSBJhw.js +0 -1
- package/viewer-dist/assets/blade-BrDpNfUX.js +0 -1
- package/viewer-dist/assets/bsl-gRq8cI6V.js +0 -1
- package/viewer-dist/assets/c-DWGmR78Y.js +0 -1
- package/viewer-dist/assets/c-SSSlmE39.js +0 -1
- package/viewer-dist/assets/cairo-D66nqRlU.js +0 -1
- package/viewer-dist/assets/clojure-BrC3BItl.js +0 -1
- package/viewer-dist/assets/cmake-BRht3inD.js +0 -1
- package/viewer-dist/assets/coffee-drHG6SJT.js +0 -1
- package/viewer-dist/assets/constants-CmGPilXJ.js +0 -1
- package/viewer-dist/assets/core-B86SFyc0.js +0 -1
- package/viewer-dist/assets/cpp-BDT6bThX.js +0 -1
- package/viewer-dist/assets/cpp-CcLCVKG_.js +0 -1
- package/viewer-dist/assets/csharp-DtuFCOLR.js +0 -1
- package/viewer-dist/assets/css-BGIxQoYs.js +0 -1
- package/viewer-dist/assets/css-DUjzNfgv.js +0 -1
- package/viewer-dist/assets/csv-D6mwZ2PH.js +0 -1
- package/viewer-dist/assets/dart-B8JJT_EX.js +0 -1
- package/viewer-dist/assets/diff-B0S3HUPm.js +0 -1
- package/viewer-dist/assets/docker-B3DZKTds.js +0 -1
- package/viewer-dist/assets/edge-B_SBzXGF.js +0 -1
- package/viewer-dist/assets/elixir-B0EKSUNS.js +0 -1
- package/viewer-dist/assets/erlang-CCXss5H6.js +0 -1
- package/viewer-dist/assets/erlang-DAWODyxE.js +0 -1
- package/viewer-dist/assets/formatCSSVariablePrefix-KRh9vnZf.js +0 -1
- package/viewer-dist/assets/fortran-fixed-form-1cK5gXa1.js +0 -1
- package/viewer-dist/assets/fortran-free-form-9zh5t3u2.js +0 -1
- package/viewer-dist/assets/fsharp-C37UASp4.js +0 -1
- package/viewer-dist/assets/fsharp-D8ZPuVlk.js +0 -1
- package/viewer-dist/assets/gdresource-LxjHb83i.js +0 -1
- package/viewer-dist/assets/gdscript-C2iVvkL_.js +0 -1
- package/viewer-dist/assets/gdshader-BpaOOKdG.js +0 -1
- package/viewer-dist/assets/git-commit-BAuDFD-1.js +0 -1
- package/viewer-dist/assets/git-commit-rNeRxB9Y.js +0 -1
- package/viewer-dist/assets/git-rebase-Cpv8mbcu.js +0 -1
- package/viewer-dist/assets/glsl-CaPTrB3a.js +0 -1
- package/viewer-dist/assets/glsl-ThNHWs2E.js +0 -1
- package/viewer-dist/assets/go-BrE3Phef.js +0 -1
- package/viewer-dist/assets/graphql-DAzSVzvB.js +0 -1
- package/viewer-dist/assets/graphql-DEIChqxY.js +0 -1
- package/viewer-dist/assets/groovy-D_Q3n-An.js +0 -1
- package/viewer-dist/assets/haml-C1zHJAQt.js +0 -1
- package/viewer-dist/assets/haml-mwfMQlUs.js +0 -1
- package/viewer-dist/assets/handlebars-CEZndQNl.js +0 -1
- package/viewer-dist/assets/haxe-j5FdAS1V.js +0 -1
- package/viewer-dist/assets/hlsl-C3sg_olF.js +0 -1
- package/viewer-dist/assets/html-DSw1lh5G.js +0 -1
- package/viewer-dist/assets/html-WQKKblVZ.js +0 -1
- package/viewer-dist/assets/html-derivative-CjJKezcp.js +0 -1
- package/viewer-dist/assets/hxml-DPF7XkXa.js +0 -1
- package/viewer-dist/assets/index-CVKGwJkR.js +0 -255
- package/viewer-dist/assets/ini-DxURaTxO.js +0 -1
- package/viewer-dist/assets/java-BtIQNnN0.js +0 -1
- package/viewer-dist/assets/java-DxlWrXwe.js +0 -1
- package/viewer-dist/assets/javascript-BzbQS41l.js +0 -1
- package/viewer-dist/assets/javascript-Yelw-5ZN.js +0 -1
- package/viewer-dist/assets/json-B88Oqtu5.js +0 -1
- package/viewer-dist/assets/json-CaljABEy.js +0 -1
- package/viewer-dist/assets/jsonc-CTI_jrid.js +0 -1
- package/viewer-dist/assets/jsx-D3KKoC5L.js +0 -1
- package/viewer-dist/assets/jsx-hEbJ82HF.js +0 -1
- package/viewer-dist/assets/julia-BCOw4cyx.js +0 -1
- package/viewer-dist/assets/julia-hqywDEUR.js +0 -1
- package/viewer-dist/assets/just-Br47BmIC.js +0 -1
- package/viewer-dist/assets/langs-JgP7EaER.js +0 -2
- package/viewer-dist/assets/latex-Djh9Fg1h.js +0 -1
- package/viewer-dist/assets/less-GWsDhusf.js +0 -1
- package/viewer-dist/assets/lib-IuaA1a0_.js +0 -9
- package/viewer-dist/assets/loader-D4gJynmd.js +0 -1
- package/viewer-dist/assets/log-DSUv6hjM.js +0 -1
- package/viewer-dist/assets/lua-BJObVtAx.js +0 -1
- package/viewer-dist/assets/lua-DjuecEsk.js +0 -1
- package/viewer-dist/assets/make-BLT6fICl.js +0 -1
- package/viewer-dist/assets/markdown-Cla8Gbs6.js +0 -1
- package/viewer-dist/assets/marko-DPS0EkZ1.js +0 -1
- package/viewer-dist/assets/mdc-C6srEd4p.js +0 -1
- package/viewer-dist/assets/nextflow-groovy-1acFxZ7Y.js +0 -1
- package/viewer-dist/assets/nextflow-uA5IJerx.js +0 -1
- package/viewer-dist/assets/nim-Dr8hIC6Y.js +0 -1
- package/viewer-dist/assets/nim-ZjzS1dcU.js +0 -1
- package/viewer-dist/assets/objective-c-DMLMCfZd.js +0 -1
- package/viewer-dist/assets/ocaml-oSZO9LTw.js +0 -1
- package/viewer-dist/assets/org-B3Y3gBCc.js +0 -1
- package/viewer-dist/assets/perl-Di9CLCS0.js +0 -1
- package/viewer-dist/assets/php-DXPvgw5o.js +0 -1
- package/viewer-dist/assets/postcss-e3XvZOFQ.js +0 -1
- package/viewer-dist/assets/powershell-DyPZnz5v.js +0 -1
- package/viewer-dist/assets/preload-helper-BZ1Pz5am.js +0 -1
- package/viewer-dist/assets/pug-BlofpNpK.js +0 -1
- package/viewer-dist/assets/python-ORI17Sev.js +0 -1
- package/viewer-dist/assets/r-DWzjseEo.js +0 -1
- package/viewer-dist/assets/r-Dr1JUpHl.js +0 -1
- package/viewer-dist/assets/raku-B6hKIqfP.js +0 -1
- package/viewer-dist/assets/regexp-B4pBNbU3.js +0 -1
- package/viewer-dist/assets/regexp-BWpGejPw.js +0 -1
- package/viewer-dist/assets/rst-DT-C-5fA.js +0 -1
- package/viewer-dist/assets/ruby-BwIxDKXu.js +0 -1
- package/viewer-dist/assets/rust-tUOVui2B.js +0 -1
- package/viewer-dist/assets/scala-Dcd77NNm.js +0 -1
- package/viewer-dist/assets/scss-CWs8DVSa.js +0 -1
- package/viewer-dist/assets/scss-Dec6wfVg.js +0 -1
- package/viewer-dist/assets/sdbl-DFPhMlBm.js +0 -1
- package/viewer-dist/assets/shaderlab-DY7g_Ava.js +0 -1
- package/viewer-dist/assets/shellscript-BiGZg9Om.js +0 -1
- package/viewer-dist/assets/shellscript-CqHdAlCp.js +0 -1
- package/viewer-dist/assets/shiki-BYYByAlk.js +0 -2
- package/viewer-dist/assets/sparql-Dy5Sx-zJ.js +0 -1
- package/viewer-dist/assets/sql-BOsskAmu.js +0 -1
- package/viewer-dist/assets/sql-CNu3Or2W.js +0 -1
- package/viewer-dist/assets/stylus-BOYZFyl7.js +0 -1
- package/viewer-dist/assets/svelte-BaCIHHWd.js +0 -1
- package/viewer-dist/assets/swift-CpxeRS9H.js +0 -1
- package/viewer-dist/assets/system-verilog-CIGW6CHD.js +0 -1
- package/viewer-dist/assets/templ-BfgLc4ra.js +0 -1
- package/viewer-dist/assets/tex-C9L8xJex.js +0 -1
- package/viewer-dist/assets/tex-CeakZqzU.js +0 -1
- package/viewer-dist/assets/themes-DP0gt5jG.js +0 -2
- package/viewer-dist/assets/tsx-5f3ulCja.js +0 -1
- package/viewer-dist/assets/tsx-BOvsFOI6.js +0 -1
- package/viewer-dist/assets/turtle-B2uMLKuz.js +0 -1
- package/viewer-dist/assets/twig-BuizuR2K.js +0 -1
- package/viewer-dist/assets/twig-p9meEoSL.js +0 -1
- package/viewer-dist/assets/typescript-Utq2Cl8c.js +0 -1
- package/viewer-dist/assets/typescript-j_1H8WHN.js +0 -1
- package/viewer-dist/assets/typst-qZ7a-KdK.js +0 -1
- package/viewer-dist/assets/unwrapDefault-ByDmBtHB.js +0 -1
- package/viewer-dist/assets/vb-Dcr14nCw.js +0 -1
- package/viewer-dist/assets/verilog-DUw2aqD4.js +0 -1
- package/viewer-dist/assets/vue-qH43U_rv.js +0 -1
- package/viewer-dist/assets/vue-vine-6XI2pIvQ.js +0 -1
- package/viewer-dist/assets/xml-CoDIzWF0.js +0 -1
- package/viewer-dist/assets/xml-WY0zc4PG.js +0 -1
- package/viewer-dist/assets/xsl-ChYNfH-b.js +0 -1
- package/viewer-dist/assets/yaml-CxbubiML.js +0 -1
- package/viewer-dist/assets/yaml-DijMHRDA.js +0 -1
- package/viewer-dist/assets/zig-VWdiCTxG.js +0 -1
package/README.md
CHANGED
|
@@ -6,29 +6,31 @@ Use it to explain an existing workflow, plan future work, or review a change. Do
|
|
|
6
6
|
|
|
7
7
|
## Try it
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
The `product-doc` CLI is available on npm, and the `generate-product-doc` skill is available in this public repository. You need Git, Node.js 22 or newer, npm, and a coding agent with repository and shell access.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
From your project, ask your agent:
|
|
12
12
|
|
|
13
|
-
```
|
|
14
|
-
|
|
13
|
+
```text
|
|
14
|
+
Install the generate-product-doc skill from tanishqkancharla/diffmap, then use it to explain how this project works.
|
|
15
15
|
```
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
Or install the skill yourself, selecting your coding agent when prompted:
|
|
18
18
|
|
|
19
|
-
```
|
|
20
|
-
|
|
19
|
+
```sh
|
|
20
|
+
npx skills add tanishqkancharla/diffmap --skill generate-product-doc
|
|
21
21
|
```
|
|
22
22
|
|
|
23
|
-
|
|
23
|
+
For a non-interactive Amp installation, add `--agent amp --yes`. Then ask your agent to use `generate-product-doc` to explain a system, plan work, or review changes. If the current session does not discover the installed skill, reload its skills or start a new session.
|
|
24
|
+
|
|
25
|
+
Installing the skill and acquiring the CLI are separate steps. The skill is a short pointer: your agent loads the full instructions from `npx product-doc guide`, which acquires the CLI from npm and keeps its instructions version-matched to the viewer. Running that command alone does not install the skill. When the stub itself changes, update it with `npx skills update generate-product-doc`.
|
|
24
26
|
|
|
25
27
|
The skill keeps documents in `.diffmap/specs/<name>/`. Productdoc is open source and MIT licensed. Documents are served locally by default; [sharing as an unlisted gist](#share-a-spec-with-a-link-experimental) still uses diffmap.dev until productdoc.dev supports those links.
|
|
26
28
|
|
|
27
29
|
### Migrating from Diffmap
|
|
28
30
|
|
|
29
|
-
Productdoc is the standalone successor to Diffmap, expanding beyond diff review. The npm package is `product-doc`, its executable is `product-doc`, and its website
|
|
31
|
+
Productdoc is the standalone successor to Diffmap, expanding beyond diff review. The npm package is `product-doc`, its executable is `product-doc`, and its website is [productdoc.dev](https://productdoc.dev). The GitHub repository keeps its current URL.
|
|
30
32
|
|
|
31
|
-
|
|
33
|
+
Diffmap is being retired. Use `generate-product-doc` and `product-doc` for new work, not the legacy skill or package. Existing installs do not migrate automatically. Keep existing documents and shared links rather than copying or deleting them; Productdoc still reads `.diffmap/specs/`. No legacy binary alias or automatic installation migration is added.
|
|
32
34
|
|
|
33
35
|
[The original Diffmap launch video](https://x.com/tanishqk/status/2116212881125691850) shows the review workflow this builds on.
|
|
34
36
|
|
|
@@ -160,7 +162,7 @@ npx product-doc share .diffmap/specs/<name>/
|
|
|
160
162
|
|
|
161
163
|
A spec's pages share one gist. Hosted viewer: `https://diffmap.dev/g/<gistId>` for the cover, and `/<slug>` after it for a page (`#heading` is the table of contents). Gists shared before specs were directories still open, one file at a time. The page fetches the gist in the browser from `api.github.com`. Gists are unlisted, not private.
|
|
162
164
|
|
|
163
|
-
A spec committed to a GitHub pull request also opens at `https://diffmap.dev/<owner>/<repo>/pull/<n>/.diffmap/specs/<name
|
|
165
|
+
A spec committed to a GitHub pull request also opens at `https://diffmap.dev/<owner>/<repo>/pull/<n>/.diffmap/specs/<name>`, which pins to the pull request's head commit and opens the spec's cover. Its pages keep their file names in the URL, as in `…/commit/<sha>/.diffmap/specs/<name>/02-write-through.md`, since a pinned commit never renames them.
|
|
164
166
|
|
|
165
167
|
## Library
|
|
166
168
|
|
|
@@ -319,8 +321,8 @@ Append a reference to a call stack line to link it. Paths are relative to `--roo
|
|
|
319
321
|
- `[[path/to/file]]` links a whole file and `[[path/to/file#L12-L30]]` a line
|
|
320
322
|
range. These work with any language.
|
|
321
323
|
- `[[<sha>:path/to/file#L12-L30]]` or `[[<sha>:path/to/file]]` links a change
|
|
322
|
-
in a commit. `<sha>` is a 7–40 character lowercase
|
|
323
|
-
`<sha>..<sha>`.
|
|
324
|
+
or an unchanged file in a commit. `<sha>` is a 7–40 character lowercase
|
|
325
|
+
commit SHA, or a range `<sha>..<sha>`.
|
|
324
326
|
|
|
325
327
|
```callstack
|
|
326
328
|
shareMarkdownFile [[src/share.ts#shareMarkdownFile]]
|
|
@@ -333,10 +335,11 @@ uncommitted changes, the panel shows the current file.
|
|
|
333
335
|
|
|
334
336
|
A commit reference opens the Diff panel on every file changed in that commit or
|
|
335
337
|
range, with a sticky header per file, scrolled to the linked file and lines.
|
|
336
|
-
Line numbers are the file's lines after the commit.
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
338
|
+
Line numbers are the file's lines after the commit. If the file is unchanged,
|
|
339
|
+
the panel shows its source at that commit (or the destination of a range),
|
|
340
|
+
not the working tree. The file must exist there and the range must fit;
|
|
341
|
+
`serve` and `share` run git and fail at startup otherwise. Deleted lines cannot
|
|
342
|
+
be referenced, and a commit cannot be combined with `#symbol`.
|
|
340
343
|
|
|
341
344
|
Multiple references on one stack line are allowed. The references are hidden in
|
|
342
345
|
the rendered stack, and linked rows support mouse clicks and keyboard activation.
|
|
@@ -381,10 +384,12 @@ the pull request's full diff.
|
|
|
381
384
|
|
|
382
385
|
A shared gist is a snapshot taken when you run `product-doc share`. It saves every
|
|
383
386
|
referenced commit and every `changes` card, including uncommitted ones, to
|
|
384
|
-
`diffmap-changes.json
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
387
|
+
`diffmap-changes.json`, with unchanged supporting files saved at each referenced
|
|
388
|
+
revision separately from the changed-file list. It saves the current contents
|
|
389
|
+
of every file that a file excerpt or a reference without a commit reads to
|
|
390
|
+
`diffmap-files.json`. In the gist, references without a commit open that saved
|
|
391
|
+
file; symbols resolve to their first matching line, and Cmd-click definitions
|
|
392
|
+
only work in a local viewer. Commit
|
|
388
393
|
your work and point references at the commit before sharing, so the gist shows
|
|
389
394
|
the diff instead of a bare file.
|
|
390
395
|
|
|
@@ -564,4 +569,8 @@ Turn it off with `DIFFMAP_TELEMETRY=0` (or `false`) or `DO_NOT_TRACK=1`. It is a
|
|
|
564
569
|
|
|
565
570
|
## Feedback
|
|
566
571
|
|
|
567
|
-
Found a bug, hit a confusing error, or want a feature? [
|
|
572
|
+
Found a bug, hit a confusing error, or want a feature? Search [existing issues](https://github.com/tanishqkancharla/diffmap/issues), then comment on a matching issue or [open a new one](https://github.com/tanishqkancharla/diffmap/issues/new). Describe what you did, what you expected, and what happened, with your Productdoc version (`product-doc --version`). Keep submissions de-identified and prose-only, without PII, code, attachments, or identifying details.
|
|
573
|
+
|
|
574
|
+
Agents follow the [guide's Feedback section](guide.md#feedback) through `gh`, adding the `agent-feedback` label when available and the footer “Reported via Productdoc agent feedback” to issue bodies and comments. Diagnostic metadata is limited to the Productdoc version and agent product name, if known.
|
|
575
|
+
|
|
576
|
+
These markers identify the reporting path, not verified origin. This is guidance, not enforced anonymization: GitHub still shows the submitting account.
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Live previews
|
|
2
|
+
|
|
3
|
+
A `preview` or `flow` block runs the app's real components in the spec, from the app's own Storybook stories. Use a `preview` block for a component or a design, with its variants side by side. Use a `flow` block for a journey of several states, or one that branches. Keep screenshots for UI that has no story, such as a whole page that needs a real backend.
|
|
4
|
+
|
|
5
|
+
````text
|
|
6
|
+
```preview [The log-in screen]
|
|
7
|
+
auth-log-in--empty
|
|
8
|
+
auth-log-in--wrong-password
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
```flow [Logging in]
|
|
12
|
+
auth-log-in--empty
|
|
13
|
+
auth-log-in--filled: Fill in email and password
|
|
14
|
+
auth-log-in--signed-in: Log in
|
|
15
|
+
auth-log-in--wrong-password: Log in with the wrong password
|
|
16
|
+
auth-log-in--forgot: Click "Forgot password?"
|
|
17
|
+
```
|
|
18
|
+
````
|
|
19
|
+
|
|
20
|
+
Name stories by their Storybook ID. In a `flow`, the first line is the starting state, and each later story is indented two spaces under the state it follows, with the action that leads to it after a colon. List the happy path first: the block's next-step button follows a state's first child.
|
|
21
|
+
|
|
22
|
+
**Set up the app once.** Skip this if the repo's `.diffmap/config.json` already has `previews`.
|
|
23
|
+
|
|
24
|
+
1. If the app has no Storybook, add `@storybook/react` and `storybook` as dev dependencies; no Storybook server or config is needed. For screens that call the server, add `msw` and `msw-storybook-addon`, run `npx msw init public`, and add `mswLoader` to the preview's `loaders`.
|
|
25
|
+
2. Add a page that the dev server and preview deployments serve, and the production deployment leaves out. In a Vite app, it is a `previews.html` beside `index.html`, added to `build.rollupOptions.input` only when the build is not for production, such as when `VERCEL_ENV` is not `production`. It loads:
|
|
26
|
+
|
|
27
|
+
```tsx
|
|
28
|
+
import { createRoot } from "react-dom/client";
|
|
29
|
+
import { setProjectAnnotations } from "@storybook/react";
|
|
30
|
+
import { PreviewRoute } from "product-doc/preview";
|
|
31
|
+
import preview from "../../.storybook/preview";
|
|
32
|
+
|
|
33
|
+
setProjectAnnotations([preview]);
|
|
34
|
+
const stories = import.meta.glob("../**/*.stories.tsx", { eager: true });
|
|
35
|
+
createRoot(document.getElementById("root")!).render(
|
|
36
|
+
<PreviewRoute stories={stories} />,
|
|
37
|
+
);
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
In a Next.js app, it is `app/__previews/page.tsx`, which calls `notFound()` on the production deployment, such as when `VERCEL_ENV` is `production`, and otherwise renders a client component with the same `PreviewRoute`, passing the story modules imported by hand. Import the project's `.storybook/preview` when it exists, so every story gets the app's decorators, providers, and global styles.
|
|
41
|
+
|
|
42
|
+
3. Send `previewFrameAncestors`, from `product-doc/preview`, as the page's `Content-Security-Policy` header, so only the local viewer and diffmap.dev can frame it: from the dev server, as with Vite's `server.headers`, and from preview deployments, as with `headers` in `vercel.json` or `headers()` in `next.config`.
|
|
43
|
+
4. Add the page's URLs to `.diffmap/config.json` at the repo root. `local` is the page on the dev server. `preview` is the page on each pull request's preview deployment, with `{branch}`, `{sha}`, or `{pull}`; diffmap.dev fills them from the pull request, with `{branch}` lowercase and every run of characters other than letters and digits turned into `-`, as Vercel and Netlify put a branch in a hostname. The deployment must be public, or diffmap.dev shows that it can't reach it.
|
|
44
|
+
|
|
45
|
+
```json [.diffmap/config.json]
|
|
46
|
+
{
|
|
47
|
+
"previews": {
|
|
48
|
+
"local": "http://localhost:5173/previews.html",
|
|
49
|
+
"preview": "https://myapp-git-{branch}-myteam.vercel.app/previews.html"
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Add a `flows` key only to change a flow's defaults: `"transitions": "render"` draws each state from the start instead of playing the step on the live UI, and `"viewport": { "width": 1280, "height": 800 }` sets the size of the expanded flow.
|
|
55
|
+
|
|
56
|
+
**Write the stories.**
|
|
57
|
+
|
|
58
|
+
- Reuse the team's stories where they exist. Write new ones next to the component, in Storybook's format, with a `title`.
|
|
59
|
+
- Answer every request from the story's `parameters.msw.handlers`, never a live backend: previews must not sign anyone in, charge a card, or change real data. Use fixed values, not timestamps or random content.
|
|
60
|
+
- In a flow, each story after the first is one step from the story it is indented under. Its `play` does what the person does next, through `canvas` and `userEvent`, and its handlers give the server's answer to that step. Don't repeat the parent's steps: diffmap plays the path for you.
|
|
61
|
+
- Model events from outside the app, such as an email link or a provider's approval, as their own step with an action, not as buttons added to the UI.
|
|
62
|
+
- Write each story's `parameters.docs.description.story` as the state's note: what just happened, what is saved or still pending, and what the person can do next. Mark behavior that does not exist yet as proposed.
|
|
63
|
+
|
|
64
|
+
**Check before handing back.** With the app's dev server running, open each story on its own at `<previews.local>?story=<id>`, and each flow state at `?story=<id>&path=<ids from the start>`. Fix what the page lists as wrong with a story file. Then open the spec with `serve`, step through every state of each flow, and compare the states with the running app. The blocks show live UI only while the dev server runs; on a pull request, they load its preview deployment.
|
package/guide/ui.md
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Capture UI changes
|
|
2
|
+
|
|
3
|
+
When a phase changes a UI that has Storybook stories, or could have them, show it live instead: run `npx product-doc guide previews`. Otherwise, capture the running app with the browser automation you have, such as Playwright or agent-browser, and add the captures to the phase. They let the reader judge the result without running it, and they test your work: before you add a capture, look at it with the expected result in mind, and fix what it shows wrong. Skip captures for changes nobody sees, such as a refactor or a backend fix with no visible effect.
|
|
4
|
+
|
|
5
|
+
- Use screenshots by default: they show how a state looks. Take one per state, variant, or window width the change affects, default first, such as empty, loading, error, hover, or a narrow window, and label each with the state it shows.
|
|
6
|
+
- Record a clip only for what screenshots cannot show: hover and click feedback, menus, focus, dragging, transitions, or timing. Move a real pointer through the whole interaction, past neighboring controls, and keep the clip under about 15 seconds.
|
|
7
|
+
- Show Today beside Proposed when the comparison is the point, in a `side-by-side` gallery. Capture Today from the unchanged code, such as the base commit in a worktree, not from a mockup. Use `grid` to scan several states or variants, and `carousel` to step through the stages of a flow.
|
|
8
|
+
- Keep only captures that help the reader decide something. Leave out intermediate attempts; when a fix changes the UI, replace the capture so only the final one remains.
|
|
9
|
+
- Crop screenshots to the part that changed, keep text readable, and leave out secrets and personal data.
|
|
10
|
+
- Save captures under `media/<phase-slug>/` in the spec and link them relative to the page, as in `media/write-through/save.png`. Prefer `.mp4` for recordings, since every browser plays it. Commit them with the spec so the pull request viewer shows them; ask the user before committing more than a few megabytes.
|
|
11
|
+
- Above each capture, say in a sentence what to look for. Readers comment by highlighting that sentence or a gallery label, and **Copy comments** brings their notes back to you.
|
|
12
|
+
- A capture shows what happened; it does not prove the behavior. Say which checks you ran.
|
|
13
|
+
- `share` fails on local media. To share a spec with captures, link them by https URL, or open the spec on its pull request.
|
package/guide.md
CHANGED
|
@@ -37,7 +37,7 @@ npx product-doc share .diffmap/specs/<name>/ # only when asked; prints https:
|
|
|
37
37
|
|
|
38
38
|
`validate` checks every page's syntax, diagrams, and annotations, and the spec's page names, without starting a server; it does not resolve source files or Git commits. Fix validation errors before handing back the viewer. After updating productdoc itself, restart existing viewers to load its new parser.
|
|
39
39
|
|
|
40
|
-
Leave the server running and give the user the directory and URL. It reloads a page when you edit it, and the page list when you add, remove, or retitle a page. Inspect the rendered document's diagrams, prose previews, and media before handing it back. Before sharing, commit finished work and point its references at the commit, as in [When a phase is complete](#when-a-phase-is-complete): `share` saves each referenced commit's diff into the gist, but a reference without a commit only opens the file as it was when shared. A shared gist is unlisted: anyone with the URL can read it, including every file it snapshots. A spec on a pull request is also at `https://diffmap.dev/<owner>/<repo>/pull/<n>/.diffmap/specs/<name
|
|
40
|
+
Leave the server running and give the user the directory and URL. It reloads a page when you edit it, and the page list when you add, remove, or retitle a page. Inspect the rendered document's diagrams, prose previews, and media before handing it back. Before sharing, commit finished work and point its references at the commit, as in [When a phase is complete](#when-a-phase-is-complete): `share` saves each referenced commit's diff into the gist, but a reference without a commit only opens the file as it was when shared. A shared gist is unlisted: anyone with the URL can read it, including every file it snapshots. A spec on a pull request is also at `https://diffmap.dev/<owner>/<repo>/pull/<n>/.diffmap/specs/<name>`, pinned to a commit.
|
|
41
41
|
|
|
42
42
|
## Shape
|
|
43
43
|
|
|
@@ -81,7 +81,7 @@ Use `services` when the parts keep state, run at the same time, or fan out; use
|
|
|
81
81
|
|
|
82
82
|
**Links.** Link existing source with [references](#source-references); write planned symbols as plain text.
|
|
83
83
|
|
|
84
|
-
**Screenshots and recordings.** When a phase changes something a person sees, show it;
|
|
84
|
+
**Screenshots and recordings.** When a phase changes something a person sees, show it, live in a `preview` or `flow` block or in captures; `product-doc guide ui` says which to use. Write ``; a `.mp4` or `.webm` path renders as a video player. Group related captures in a `:::gallery side-by-side`, `grid`, or `carousel`, and title a carousel like `:::gallery carousel [Saving a record]`. Each item's alt text is its visible label, and a gallery holds only images and videos.
|
|
85
85
|
|
|
86
86
|
```md
|
|
87
87
|
:::gallery side-by-side
|
|
@@ -207,19 +207,9 @@ src/request.test.ts
|
|
|
207
207
|
```
|
|
208
208
|
````
|
|
209
209
|
|
|
210
|
-
##
|
|
210
|
+
## UI changes
|
|
211
211
|
|
|
212
|
-
When a phase changes a UI,
|
|
213
|
-
|
|
214
|
-
- Use screenshots by default: they show how a state looks. Take one per state, variant, or window width the change affects, default first, such as empty, loading, error, hover, or a narrow window, and label each with the state it shows.
|
|
215
|
-
- Record a clip only for what screenshots cannot show: hover and click feedback, menus, focus, dragging, transitions, or timing. Move a real pointer through the whole interaction, past neighboring controls, and keep the clip under about 15 seconds.
|
|
216
|
-
- Show Today beside Proposed when the comparison is the point, in a `side-by-side` gallery. Capture Today from the unchanged code, such as the base commit in a worktree, not from a mockup. Use `grid` to scan several states or variants, and `carousel` to step through the stages of a flow.
|
|
217
|
-
- Keep only captures that help the reader decide something. Leave out intermediate attempts; when a fix changes the UI, replace the capture so only the final one remains.
|
|
218
|
-
- Crop screenshots to the part that changed, keep text readable, and leave out secrets and personal data.
|
|
219
|
-
- Save captures under `media/<phase-slug>/` in the spec and link them relative to the page, as in `media/write-through/save.png`. Prefer `.mp4` for recordings, since every browser plays it. Commit them with the spec so the pull request viewer shows them; ask the user before committing more than a few megabytes.
|
|
220
|
-
- Above each capture, say in a sentence what to look for. Readers comment by highlighting that sentence or a gallery label, and **Copy comments** brings their notes back to you.
|
|
221
|
-
- A capture shows what happened; it does not prove the behavior. Say which checks you ran.
|
|
222
|
-
- `share` fails on local media. To share a spec with captures, link them by https URL, or open the spec on its pull request.
|
|
212
|
+
When a phase changes a UI, run `npx product-doc guide ui` and follow what it prints: when to show the UI live, and how to take screenshots and recordings. To show it live, from the app's Storybook stories, run `npx product-doc guide previews`, which covers the `preview` and `flow` blocks and setting them up in the app.
|
|
223
213
|
|
|
224
214
|
## Source references
|
|
225
215
|
|
|
@@ -236,14 +226,27 @@ Fences: `mermaid` draws a diagram, `services` an animated diagram of services, t
|
|
|
236
226
|
|
|
237
227
|
## Feedback
|
|
238
228
|
|
|
239
|
-
When productdoc gets in your way or the user has feedback on it, such as a rendering bug, a confusing error, a missing feature, or advice in this guide that did not work,
|
|
229
|
+
When productdoc gets in your way or the user has feedback on it, such as a rendering bug, a confusing error, a missing feature, or advice in this guide that did not work, report it on the existing GitHub repo. Search first, and comment on a matching issue instead of opening a duplicate:
|
|
240
230
|
|
|
241
231
|
```sh
|
|
242
232
|
gh issue list --repo tanishqkancharla/diffmap --search "<keywords>" --state all
|
|
243
|
-
gh issue create --repo tanishqkancharla/diffmap --title "<
|
|
233
|
+
gh issue create --repo tanishqkancharla/diffmap --title "<summary>" --body "<details and footer>"
|
|
234
|
+
gh issue comment "<issue-number>" --repo tanishqkancharla/diffmap --body "<details and footer>"
|
|
244
235
|
```
|
|
245
236
|
|
|
246
|
-
|
|
237
|
+
Describe what you did, what you expected, and what happened. Keep titles, issue bodies, and comments de-identified and prose-only: no PII, code or spec snippets, raw logs, screenshots, credentials, or identifying details (including private paths, repository/customer names, and links).
|
|
238
|
+
|
|
239
|
+
End agent-submitted issue bodies and comments with this footer. Include only the Productdoc version (`npx product-doc --version`) and agent product name as diagnostic metadata; omit the agent line if unknown:
|
|
240
|
+
|
|
241
|
+
```text
|
|
242
|
+
Reported via Productdoc agent feedback
|
|
243
|
+
Productdoc version: <version>
|
|
244
|
+
Agent: <product name>
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
Add `--label agent-feedback` when creating an issue if the label is available; otherwise keep the footer and submit without it. Ask before changing shared label configuration. These markers identify the reporting path, not verified origin.
|
|
248
|
+
|
|
249
|
+
This is guidance, not enforced anonymization: GitHub still shows the submitting account. Give the user the issue URL.
|
|
247
250
|
|
|
248
251
|
## Look up the rest
|
|
249
252
|
|
package/lib/changes.d.ts
CHANGED
|
@@ -73,7 +73,11 @@ export type Changes = {
|
|
|
73
73
|
/** GitHub listed only the first files; `url` has the rest. */
|
|
74
74
|
truncated?: boolean;
|
|
75
75
|
files: ChangedFile[];
|
|
76
|
+
/** Unchanged supporting files at this rev's destination, keyed by path. */
|
|
77
|
+
sources?: Record<string, string>;
|
|
76
78
|
};
|
|
79
|
+
/** Spec metadata is not part of the code review; match directories, not substrings. */
|
|
80
|
+
export declare function summaryFiles(files: ChangedFile[]): ChangedFile[];
|
|
77
81
|
/**
|
|
78
82
|
* Splits files into the ones to review, in `review` order, and the rest in
|
|
79
83
|
* their original order. Listing no files at all means every file is to be
|
package/lib/changes.js
CHANGED
|
@@ -88,12 +88,17 @@ export function windowLabel(deltas, window) {
|
|
|
88
88
|
const from = oldest.kind === "commit" ? oldest.parent.slice(0, 7) : deltaName(oldest);
|
|
89
89
|
return `${from}…${deltaName(newest)}`;
|
|
90
90
|
}
|
|
91
|
+
/** Spec metadata is not part of the code review; match directories, not substrings. */
|
|
92
|
+
export function summaryFiles(files) {
|
|
93
|
+
return files.filter((file) => !file.path.split("/").slice(0, -1).includes(".diffmap"));
|
|
94
|
+
}
|
|
91
95
|
/**
|
|
92
96
|
* Splits files into the ones to review, in `review` order, and the rest in
|
|
93
97
|
* their original order. Listing no files at all means every file is to be
|
|
94
98
|
* reviewed; listing only files to ignore means none is.
|
|
95
99
|
*/
|
|
96
100
|
export function orderForReview(files, review, ignore = []) {
|
|
101
|
+
files = summaryFiles(files);
|
|
97
102
|
if (review.length === 0 && ignore.length === 0)
|
|
98
103
|
return { reviewed: files, other: [] };
|
|
99
104
|
const reviewed = review.flatMap((path) => files.find((file) => file.path === path) ?? []);
|
package/lib/cli.js
CHANGED
|
@@ -5,6 +5,7 @@ import { packageVersion } from "./packageVersion.js";
|
|
|
5
5
|
import { listRunningDiffmaps } from "./registry.js";
|
|
6
6
|
import { exitAfterTelemetry, track, trackCommand } from "./telemetry.js";
|
|
7
7
|
import { detectInstallMethod, fetchLatestVersion, packageName, resolveUpdateArgv, runCommand, runUpdate, } from "./update.js";
|
|
8
|
+
const guideTopics = ["ui", "previews"];
|
|
8
9
|
const serveArgs = z.object({
|
|
9
10
|
file: z
|
|
10
11
|
.string()
|
|
@@ -14,11 +15,16 @@ const serveOptions = z.object({
|
|
|
14
15
|
port: z.coerce.number().optional().describe("Port (default: a free port)"),
|
|
15
16
|
root: z.string().optional().describe("Workspace root for file excerpts"),
|
|
16
17
|
});
|
|
17
|
-
const serveOutput = z.
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
18
|
+
const serveOutput = z.union([
|
|
19
|
+
z
|
|
20
|
+
.string()
|
|
21
|
+
.describe("What serve prints unless --format or --json asks for data"),
|
|
22
|
+
z.object({
|
|
23
|
+
url: z.string(),
|
|
24
|
+
file: z.string(),
|
|
25
|
+
warnings: z.array(z.string()).optional(),
|
|
26
|
+
}),
|
|
27
|
+
]);
|
|
22
28
|
async function* runServe(c) {
|
|
23
29
|
trackCommand("serve");
|
|
24
30
|
// Loaded per command so `--version`, `list`, and `update` skip the server's dependencies.
|
|
@@ -46,7 +52,7 @@ async function* runServe(c) {
|
|
|
46
52
|
track("serve_result", { ok: false, error: started.name });
|
|
47
53
|
return c.error({
|
|
48
54
|
code: "DIFFMAP",
|
|
49
|
-
message: started.message
|
|
55
|
+
message: `Failed to serve ${c.args.file}: ${started.message.replace(/^diffmap /, "")}`,
|
|
50
56
|
});
|
|
51
57
|
}
|
|
52
58
|
// How many of each fence kind the spec uses across its pages (a kind it never uses is left out), to see which parts of the guide agents follow.
|
|
@@ -66,13 +72,27 @@ async function* runServe(c) {
|
|
|
66
72
|
file: started.filePath,
|
|
67
73
|
...(started.warnings.length > 0 ? { warnings: started.warnings } : {}),
|
|
68
74
|
};
|
|
69
|
-
|
|
75
|
+
if (c.formatExplicit)
|
|
76
|
+
yield output;
|
|
77
|
+
else {
|
|
78
|
+
const pages = started.documents.length;
|
|
79
|
+
const counts = [`${pages} page${pages === 1 ? "" : "s"}`];
|
|
80
|
+
if (started.warnings.length > 0)
|
|
81
|
+
counts.push(`${started.warnings.length} warning${started.warnings.length === 1 ? "" : "s"}`);
|
|
82
|
+
yield [
|
|
83
|
+
`Serving ${c.args.file} at ${started.url} (${counts.join(", ")})`,
|
|
84
|
+
...started.warnings.map((warning) => `Warning: ${warning}`),
|
|
85
|
+
"Stop with Ctrl+C or Close server in the viewer.",
|
|
86
|
+
].join("\n");
|
|
87
|
+
}
|
|
70
88
|
await started.closed;
|
|
71
89
|
return output;
|
|
72
90
|
}
|
|
73
91
|
const cli = Cli.create("product-doc", {
|
|
74
92
|
description: "Explain systems, plan work, and review changes as visual documents",
|
|
75
93
|
version: packageVersion,
|
|
94
|
+
// The curated authoring skill is installed separately, not generated from commands.
|
|
95
|
+
sync: false,
|
|
76
96
|
args: serveArgs,
|
|
77
97
|
options: serveOptions,
|
|
78
98
|
output: serveOutput,
|
|
@@ -157,10 +177,18 @@ const cli = Cli.create("product-doc", {
|
|
|
157
177
|
})
|
|
158
178
|
.command("guide", {
|
|
159
179
|
description: "Print the instructions agents follow to write a spec",
|
|
180
|
+
args: z.object({
|
|
181
|
+
topic: z
|
|
182
|
+
.enum(guideTopics)
|
|
183
|
+
.optional()
|
|
184
|
+
.describe("A part the main guide sends you to: ui (showing a UI change) or previews (live preview and flow blocks)"),
|
|
185
|
+
}),
|
|
160
186
|
output: z.string(),
|
|
161
|
-
run() {
|
|
187
|
+
run(c) {
|
|
162
188
|
trackCommand("guide");
|
|
163
|
-
return readFileSync(new URL(
|
|
189
|
+
return readFileSync(new URL(c.args.topic === undefined
|
|
190
|
+
? "../guide.md"
|
|
191
|
+
: `../guide/${c.args.topic}.md`, import.meta.url), "utf8");
|
|
164
192
|
},
|
|
165
193
|
})
|
|
166
194
|
.command("list", {
|
|
@@ -212,6 +240,65 @@ const cli = Cli.create("product-doc", {
|
|
|
212
240
|
return c.ok(result);
|
|
213
241
|
},
|
|
214
242
|
});
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
243
|
+
const argv = resolveUpdateArgv(process.argv.slice(2));
|
|
244
|
+
// Incur has no MCP opt-out. Block its entry points before dispatch; do not
|
|
245
|
+
// mistake an option value or a spec passed to `serve` for a command.
|
|
246
|
+
const valueOptions = new Set([
|
|
247
|
+
"--port",
|
|
248
|
+
"--root",
|
|
249
|
+
"--format",
|
|
250
|
+
"--filter-output",
|
|
251
|
+
"--token-limit",
|
|
252
|
+
"--token-offset",
|
|
253
|
+
]);
|
|
254
|
+
let command;
|
|
255
|
+
for (let index = 0; index < argv.length; index++) {
|
|
256
|
+
const arg = argv[index];
|
|
257
|
+
if (arg === "--")
|
|
258
|
+
break;
|
|
259
|
+
if (valueOptions.has(arg)) {
|
|
260
|
+
index++;
|
|
261
|
+
continue;
|
|
262
|
+
}
|
|
263
|
+
if (arg.startsWith("-") || arg === "product-doc")
|
|
264
|
+
continue;
|
|
265
|
+
command = arg;
|
|
266
|
+
break;
|
|
267
|
+
}
|
|
268
|
+
if (argv.includes("--mcp") || command === "mcp") {
|
|
269
|
+
if (!process.env.COMPLETE) {
|
|
270
|
+
process.stderr.write("MCP is not supported by product-doc. Run product-doc --help.\n");
|
|
271
|
+
exitAfterTelemetry(1);
|
|
272
|
+
}
|
|
273
|
+
}
|
|
274
|
+
else {
|
|
275
|
+
await cli.serve(argv, {
|
|
276
|
+
exit: exitAfterTelemetry,
|
|
277
|
+
stdout(output) {
|
|
278
|
+
if (process.env.COMPLETE && argv.length > 0) {
|
|
279
|
+
// Keep Incur's shell-specific encoding and all non-MCP candidates.
|
|
280
|
+
if (process.env.COMPLETE === "nushell") {
|
|
281
|
+
output = JSON.stringify(JSON.parse(output).filter((candidate) => candidate.value !== "mcp"));
|
|
282
|
+
}
|
|
283
|
+
else {
|
|
284
|
+
const separator = process.env.COMPLETE === "bash" ? "\v" : "\n";
|
|
285
|
+
output = output
|
|
286
|
+
.split(separator)
|
|
287
|
+
.filter((candidate) => candidate !== "mcp\x01" && !/^mcp(?:[:\t]|$)/.test(candidate))
|
|
288
|
+
.join(separator);
|
|
289
|
+
}
|
|
290
|
+
}
|
|
291
|
+
else if (argv.includes("--help") ||
|
|
292
|
+
argv.includes("-h") ||
|
|
293
|
+
(argv.length === 0 && process.stdout.isTTY)) {
|
|
294
|
+
output = output.replace(/^ (?:mcp|--mcp)\s.*\n/gm, "");
|
|
295
|
+
}
|
|
296
|
+
else if (output.includes("COMMAND_NOT_FOUND") &&
|
|
297
|
+
output.includes("Did you mean 'mcp'?")) {
|
|
298
|
+
process.stderr.write(`Unknown command ${JSON.stringify(command)}. Run product-doc --help.\n`);
|
|
299
|
+
return;
|
|
300
|
+
}
|
|
301
|
+
process.stdout.write(output);
|
|
302
|
+
},
|
|
303
|
+
});
|
|
304
|
+
}
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/** `.diffmap/config.json`: diffmap's one config file, found in the spec's directory or a parent of it. */
|
|
2
|
+
export type DiffmapConfig = {
|
|
3
|
+
/** Where the app's preview page lives; preview and flow blocks load it. */
|
|
4
|
+
previews?: {
|
|
5
|
+
local?: string;
|
|
6
|
+
/** A pull request's preview deployment, with {branch}, {sha}, and {pull}. */
|
|
7
|
+
preview?: string;
|
|
8
|
+
};
|
|
9
|
+
/** Settings only flow blocks use. */
|
|
10
|
+
flows?: {
|
|
11
|
+
/** "play" plays a step on the live UI; "render" draws each state from the start. */
|
|
12
|
+
transitions?: "play" | "render";
|
|
13
|
+
/** The size the expanded flow renders the app at. */
|
|
14
|
+
viewport?: {
|
|
15
|
+
width: number;
|
|
16
|
+
height: number;
|
|
17
|
+
};
|
|
18
|
+
};
|
|
19
|
+
};
|
|
20
|
+
/** What the viewer gets for the spec it shows: the config, or why it can't be read. */
|
|
21
|
+
export type ConfigLoad = {
|
|
22
|
+
config: DiffmapConfig;
|
|
23
|
+
} | {
|
|
24
|
+
error: string;
|
|
25
|
+
};
|
|
26
|
+
/** The `.diffmap/config.json` paths that apply to a spec in `specDir`, nearest first, relative to the same root. */
|
|
27
|
+
export declare function configCandidates(specDir: string): string[];
|
|
28
|
+
export declare function parseDiffmapConfig(text: string): DiffmapConfig;
|
|
29
|
+
/** The pull request a spec on diffmap.dev was opened from, which fills `previews.preview`. */
|
|
30
|
+
export type DeploymentTarget = {
|
|
31
|
+
sha: string;
|
|
32
|
+
/** The pull request's head branch. */
|
|
33
|
+
branch?: string;
|
|
34
|
+
pull?: number;
|
|
35
|
+
};
|
|
36
|
+
/**
|
|
37
|
+
* `previews.preview` with its placeholders filled. `{branch}` is the branch
|
|
38
|
+
* name as Vercel and Netlify put it in a hostname: lowercase, with every run of
|
|
39
|
+
* characters other than letters and digits turned into `-`.
|
|
40
|
+
*/
|
|
41
|
+
export declare function deploymentUrl(template: string, target: DeploymentTarget): string | Error;
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
/** The `.diffmap/config.json` paths that apply to a spec in `specDir`, nearest first, relative to the same root. */
|
|
2
|
+
export function configCandidates(specDir) {
|
|
3
|
+
const parts = specDir.split("/").filter((part) => part !== "");
|
|
4
|
+
return parts
|
|
5
|
+
.map((_, index) => parts.slice(0, parts.length - index).join("/"))
|
|
6
|
+
.concat("")
|
|
7
|
+
.map((dir) => (dir === "" ? "" : `${dir}/`) + ".diffmap/config.json");
|
|
8
|
+
}
|
|
9
|
+
export function parseDiffmapConfig(text) {
|
|
10
|
+
return checkConfig(JSON.parse(text));
|
|
11
|
+
}
|
|
12
|
+
function checkConfig(value) {
|
|
13
|
+
if (!isObject(value))
|
|
14
|
+
throw new Error("the file is not a JSON object");
|
|
15
|
+
const { previews, flows } = value;
|
|
16
|
+
if (previews !== undefined) {
|
|
17
|
+
if (!isObject(previews))
|
|
18
|
+
throw new Error("previews is an object with local and preview URLs");
|
|
19
|
+
for (const key of ["local", "preview"])
|
|
20
|
+
if (previews[key] !== undefined && typeof previews[key] !== "string")
|
|
21
|
+
throw new Error(`previews.${key} is a URL string`);
|
|
22
|
+
}
|
|
23
|
+
if (flows !== undefined) {
|
|
24
|
+
if (!isObject(flows))
|
|
25
|
+
throw new Error("flows is an object of settings");
|
|
26
|
+
if (flows.transitions !== undefined &&
|
|
27
|
+
flows.transitions !== "play" &&
|
|
28
|
+
flows.transitions !== "render")
|
|
29
|
+
throw new Error('flows.transitions is "play" or "render"');
|
|
30
|
+
const viewport = flows.viewport;
|
|
31
|
+
if (viewport !== undefined &&
|
|
32
|
+
!(isObject(viewport) &&
|
|
33
|
+
typeof viewport.width === "number" &&
|
|
34
|
+
typeof viewport.height === "number"))
|
|
35
|
+
throw new Error("flows.viewport is { width, height } in pixels");
|
|
36
|
+
}
|
|
37
|
+
// SAFETY: checked field by field above.
|
|
38
|
+
return value;
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* `previews.preview` with its placeholders filled. `{branch}` is the branch
|
|
42
|
+
* name as Vercel and Netlify put it in a hostname: lowercase, with every run of
|
|
43
|
+
* characters other than letters and digits turned into `-`.
|
|
44
|
+
*/
|
|
45
|
+
export function deploymentUrl(template, target) {
|
|
46
|
+
const values = {
|
|
47
|
+
sha: target.sha,
|
|
48
|
+
branch: target.branch === undefined
|
|
49
|
+
? undefined
|
|
50
|
+
: target.branch
|
|
51
|
+
.toLowerCase()
|
|
52
|
+
.replace(/[^a-z0-9]+/g, "-")
|
|
53
|
+
.replace(/^-|-$/g, ""),
|
|
54
|
+
pull: target.pull === undefined ? undefined : String(target.pull),
|
|
55
|
+
};
|
|
56
|
+
const missing = new Set();
|
|
57
|
+
const url = template.replace(/\{(sha|branch|pull)\}/g, (_, name) => {
|
|
58
|
+
const value = values[name];
|
|
59
|
+
if (value === undefined) {
|
|
60
|
+
missing.add(name);
|
|
61
|
+
return "";
|
|
62
|
+
}
|
|
63
|
+
return encodeURIComponent(value);
|
|
64
|
+
});
|
|
65
|
+
if (missing.size > 0)
|
|
66
|
+
return new Error(`previews.preview needs ${[...missing].map((name) => `{${name}}`).join(" and ")}, which come from the pull request.`);
|
|
67
|
+
return url;
|
|
68
|
+
}
|
|
69
|
+
function isObject(value) {
|
|
70
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
71
|
+
}
|
package/lib/git.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { type Delta, type Changes, type Rev } from "./changes.js";
|
|
2
2
|
import { DiffmapGitError } from "./errors.js";
|
|
3
3
|
import type { ChangeCard, ViewerDocument } from "./parseViewer.js";
|
|
4
|
+
import type { SourceDefinition } from "./definitions.js";
|
|
4
5
|
/** Reads the files changed by a rev, with full old and new contents. */
|
|
5
6
|
export declare function readChanges(root: string, rev: Rev): Promise<Changes | DiffmapGitError>;
|
|
6
7
|
type NumstatEntry = {
|
|
@@ -20,10 +21,14 @@ export declare function parseNumstat(output: string): NumstatEntry[];
|
|
|
20
21
|
export declare function listDeltas(root: string,
|
|
21
22
|
/** The open rev; the list reaches back far enough to show it. */
|
|
22
23
|
include?: Rev): Promise<Delta[] | DiffmapGitError>;
|
|
23
|
-
/**
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
24
|
+
/** Read a text file at a commit (or a commit range's destination), never the worktree. */
|
|
25
|
+
export declare function readSnapshotReference(root: string, reference: {
|
|
26
|
+
rev: string;
|
|
27
|
+
path: string;
|
|
28
|
+
start?: number;
|
|
29
|
+
end?: number;
|
|
30
|
+
}): Promise<SourceDefinition | DiffmapGitError>;
|
|
31
|
+
/** Load commit diffs and snapshot any unchanged supporting references. */
|
|
27
32
|
export declare function readDocumentChanges(root: string, document: Pick<ViewerDocument, "references" | "changeCards">): Promise<Map<Rev, Changes> | DiffmapGitError>;
|
|
28
33
|
/**
|
|
29
34
|
* One warning per commit `changes` card that lists files but leaves some
|