product-doc 0.0.0-stage → 0.13.2
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/LICENSE +21 -0
- package/README.md +566 -2
- package/bin.js +6 -0
- package/guide.md +251 -0
- package/lib/annotations.d.ts +44 -0
- package/lib/annotations.js +65 -0
- package/lib/changes.d.ts +96 -0
- package/lib/changes.js +111 -0
- package/lib/cli.d.ts +1 -0
- package/lib/cli.js +217 -0
- package/lib/codeNotes.d.ts +38 -0
- package/lib/codeNotes.js +113 -0
- package/lib/definitions.d.ts +23 -0
- package/lib/definitions.js +298 -0
- package/lib/diagramAnnotations.d.ts +7 -0
- package/lib/diagramAnnotations.js +27 -0
- package/lib/errors.d.ts +44 -0
- package/lib/errors.js +71 -0
- package/lib/extractDocument.d.ts +3 -0
- package/lib/extractDocument.js +22 -0
- package/lib/gist/route.d.ts +26 -0
- package/lib/gist/route.js +124 -0
- package/lib/git.d.ts +33 -0
- package/lib/git.js +474 -0
- package/lib/github/route.d.ts +28 -0
- package/lib/github/route.js +128 -0
- package/lib/index.d.ts +10 -0
- package/lib/index.js +7 -0
- package/lib/invokeCwd.d.ts +1 -0
- package/lib/invokeCwd.js +9 -0
- package/lib/media.d.ts +5 -0
- package/lib/media.js +9 -0
- package/lib/mermaid.d.ts +6 -0
- package/lib/mermaid.js +20 -0
- package/lib/mermaidTheme.d.ts +17 -0
- package/lib/mermaidTheme.js +28 -0
- package/lib/packageVersion.d.ts +1 -0
- package/lib/packageVersion.js +3 -0
- package/lib/parseFence.d.ts +76 -0
- package/lib/parseFence.js +137 -0
- package/lib/parseViewer.d.ts +74 -0
- package/lib/parseViewer.js +490 -0
- package/lib/readSpec.d.ts +25 -0
- package/lib/readSpec.js +62 -0
- package/lib/registry.d.ts +11 -0
- package/lib/registry.js +82 -0
- package/lib/serve.d.ts +70 -0
- package/lib/serve.js +756 -0
- package/lib/services.d.ts +107 -0
- package/lib/services.js +310 -0
- package/lib/share.d.ts +15 -0
- package/lib/share.js +153 -0
- package/lib/spec.d.ts +39 -0
- package/lib/spec.js +95 -0
- package/lib/telemetry.d.ts +6 -0
- package/lib/telemetry.js +109 -0
- package/lib/update.d.ts +43 -0
- package/lib/update.js +237 -0
- package/package.json +79 -4
- package/viewer-dist/assets/abap-CLvhMVsD.js +1 -0
- package/viewer-dist/assets/actionscript-3-Cs6JJXT5.js +1 -0
- package/viewer-dist/assets/ada-X3Y2mlq2.js +1 -0
- package/viewer-dist/assets/ahk-DwADkxyd.js +1 -0
- package/viewer-dist/assets/ahk2-_6rzW9BS.js +1 -0
- package/viewer-dist/assets/andromeeda-BJLMrMlp.js +1 -0
- package/viewer-dist/assets/andromeeda-vGVdxbeo.js +1 -0
- package/viewer-dist/assets/angular-html-BswFT_28.js +1 -0
- package/viewer-dist/assets/angular-html-Cwa-lTMy.js +1 -0
- package/viewer-dist/assets/angular-ts-DOMhGxLQ.js +1 -0
- package/viewer-dist/assets/apache-U0d_L8uA.js +1 -0
- package/viewer-dist/assets/apex-KFGFyKwG.js +1 -0
- package/viewer-dist/assets/apl-Dio8Ke0X.js +1 -0
- package/viewer-dist/assets/appendItems-BRdTC5zu.js +3 -0
- package/viewer-dist/assets/applescript-CCn79oCD.js +1 -0
- package/viewer-dist/assets/ara-4CJ0cIlV.js +1 -0
- package/viewer-dist/assets/asciidoc-SCjQUq34.js +1 -0
- package/viewer-dist/assets/asm-Cmm7eHzH.js +1 -0
- package/viewer-dist/assets/astro-CN6YWUG3.js +1 -0
- package/viewer-dist/assets/aurora-x-BCChoRpm.js +1 -0
- package/viewer-dist/assets/aurora-x-CDeNXAV0.js +1 -0
- package/viewer-dist/assets/awk-BWXHIvNe.js +1 -0
- package/viewer-dist/assets/ayu-dark-DluEY0Gj.js +1 -0
- package/viewer-dist/assets/ayu-dark-DzFZPuMV.js +1 -0
- package/viewer-dist/assets/ayu-light-C3h-C4tm.js +1 -0
- package/viewer-dist/assets/ayu-light-DSkcX_XD.js +1 -0
- package/viewer-dist/assets/ayu-mirage-Bqwy1Gya.js +1 -0
- package/viewer-dist/assets/ayu-mirage-DSve0zuE.js +1 -0
- package/viewer-dist/assets/ballerina-B7ZEbQpA.js +1 -0
- package/viewer-dist/assets/bat-Di-EdOIU.js +1 -0
- package/viewer-dist/assets/bat-HFWzIrao.js +1 -0
- package/viewer-dist/assets/beancount-C2IN4Vk8.js +1 -0
- package/viewer-dist/assets/berry-DKpUyyne.js +1 -0
- package/viewer-dist/assets/bibtex-CimSBJhw.js +1 -0
- package/viewer-dist/assets/bibtex-Conh3HYz.js +1 -0
- package/viewer-dist/assets/bicep-CUHmPFLl.js +1 -0
- package/viewer-dist/assets/bird2-CYIUgYqB.js +1 -0
- package/viewer-dist/assets/blade-BrDpNfUX.js +1 -0
- package/viewer-dist/assets/bsl-gRq8cI6V.js +1 -0
- package/viewer-dist/assets/c-DWGmR78Y.js +1 -0
- package/viewer-dist/assets/c-SSSlmE39.js +1 -0
- package/viewer-dist/assets/c3-D0apG41V.js +1 -0
- package/viewer-dist/assets/cadence-CQ2zXKGN.js +1 -0
- package/viewer-dist/assets/cairo-D66nqRlU.js +1 -0
- package/viewer-dist/assets/catppuccin-frappe-C9Q5zVZY.js +1 -0
- package/viewer-dist/assets/catppuccin-frappe-DbLkF0J2.js +1 -0
- package/viewer-dist/assets/catppuccin-latte-CtsyrtPq.js +1 -0
- package/viewer-dist/assets/catppuccin-latte-b6208YQK.js +1 -0
- package/viewer-dist/assets/catppuccin-macchiato-CNNBbV1L.js +1 -0
- package/viewer-dist/assets/catppuccin-macchiato-R8nAf1vR.js +1 -0
- package/viewer-dist/assets/catppuccin-mocha-DHkNF0Mp.js +1 -0
- package/viewer-dist/assets/catppuccin-mocha-DjuaAJKi.js +1 -0
- package/viewer-dist/assets/chapel-C1sUNn9S.js +1 -0
- package/viewer-dist/assets/clarity-CtfBBspg.js +1 -0
- package/viewer-dist/assets/clojure-BrC3BItl.js +1 -0
- package/viewer-dist/assets/clojure-zIjcJonk.js +1 -0
- package/viewer-dist/assets/cmake-BRht3inD.js +1 -0
- package/viewer-dist/assets/cmake-T_kMSWuN.js +1 -0
- package/viewer-dist/assets/cobol-BvqUwMCV.js +1 -0
- package/viewer-dist/assets/codeowners-C8r90Shi.js +1 -0
- package/viewer-dist/assets/codeql-oeQT6MSM.js +1 -0
- package/viewer-dist/assets/coffee-BSYIIMkB.js +1 -0
- package/viewer-dist/assets/coffee-drHG6SJT.js +1 -0
- package/viewer-dist/assets/commit-mono-latin-400-italic-BXinMwCi.woff +0 -0
- package/viewer-dist/assets/commit-mono-latin-400-italic-DjSHLl2N.woff2 +0 -0
- package/viewer-dist/assets/commit-mono-latin-400-normal-s0S3qwFW.woff +0 -0
- package/viewer-dist/assets/commit-mono-latin-400-normal-wzhe4RuD.woff2 +0 -0
- package/viewer-dist/assets/common-lisp-Cv5bFMCO.js +1 -0
- package/viewer-dist/assets/constants-CmGPilXJ.js +1 -0
- package/viewer-dist/assets/coq-CGaSfhwR.js +1 -0
- package/viewer-dist/assets/core-A38CGsfQ.js +4 -0
- package/viewer-dist/assets/core-B86SFyc0.js +1 -0
- package/viewer-dist/assets/cpp-BDT6bThX.js +1 -0
- package/viewer-dist/assets/cpp-CcLCVKG_.js +1 -0
- package/viewer-dist/assets/crystal-D0XIDmeW.js +1 -0
- package/viewer-dist/assets/csharp-B3DbjJyj.js +1 -0
- package/viewer-dist/assets/csharp-DtuFCOLR.js +1 -0
- package/viewer-dist/assets/css-BGIxQoYs.js +1 -0
- package/viewer-dist/assets/css-DUjzNfgv.js +1 -0
- package/viewer-dist/assets/csv-B_R7vXwK.js +1 -0
- package/viewer-dist/assets/csv-D6mwZ2PH.js +1 -0
- package/viewer-dist/assets/cue-CE9AQfxI.js +1 -0
- package/viewer-dist/assets/cypher-ClKdZ_lG.js +1 -0
- package/viewer-dist/assets/d-qD-0Kul2.js +1 -0
- package/viewer-dist/assets/dark-plus-BVZ_4wTZ.js +1 -0
- package/viewer-dist/assets/dark-plus-Cs2F2srj.js +1 -0
- package/viewer-dist/assets/dart-B8JJT_EX.js +1 -0
- package/viewer-dist/assets/dart-_dH3dQdM.js +1 -0
- package/viewer-dist/assets/dax-BkyTk9wS.js +1 -0
- package/viewer-dist/assets/desktop-Dlh5hvp9.js +1 -0
- package/viewer-dist/assets/diff-B0S3HUPm.js +1 -0
- package/viewer-dist/assets/diff-CR4ZX0DC.js +1 -0
- package/viewer-dist/assets/docker-B3DZKTds.js +1 -0
- package/viewer-dist/assets/docker-CAzcIhYn.js +1 -0
- package/viewer-dist/assets/dotenv-CuH5my32.js +1 -0
- package/viewer-dist/assets/dracula-BHWKrbxM.js +1 -0
- package/viewer-dist/assets/dracula-BoZgXveB.js +1 -0
- package/viewer-dist/assets/dracula-soft-5eyTD99u.js +1 -0
- package/viewer-dist/assets/dracula-soft-D-Kgh5gw.js +1 -0
- package/viewer-dist/assets/dream-maker-DW3nJb8Q.js +1 -0
- package/viewer-dist/assets/edge-B_SBzXGF.js +1 -0
- package/viewer-dist/assets/elixir-B0EKSUNS.js +1 -0
- package/viewer-dist/assets/elixir-BL8v4QDr.js +1 -0
- package/viewer-dist/assets/elk.bundled-CVOErv1M.js +24 -0
- package/viewer-dist/assets/elm-CC1TmzeR.js +1 -0
- package/viewer-dist/assets/emacs-lisp-DR2vtWaj.js +1 -0
- package/viewer-dist/assets/engine-javascript-BopS6peh.js +141 -0
- package/viewer-dist/assets/engine-oniguruma-BO8SA_1o.js +1 -0
- package/viewer-dist/assets/erb-CHbMJpQy.js +1 -0
- package/viewer-dist/assets/erlang-CCXss5H6.js +1 -0
- package/viewer-dist/assets/erlang-DAWODyxE.js +1 -0
- package/viewer-dist/assets/everforest-dark-Y6tr-2zD.js +1 -0
- package/viewer-dist/assets/everforest-dark-sB-x3p7T.js +1 -0
- package/viewer-dist/assets/everforest-light-CA0Ol4Qu.js +1 -0
- package/viewer-dist/assets/everforest-light-Df2xbC6M.js +1 -0
- package/viewer-dist/assets/fennel-DQxkIbk2.js +1 -0
- package/viewer-dist/assets/fish-BJitypiv.js +1 -0
- package/viewer-dist/assets/fluent-C03EYrpw.js +1 -0
- package/viewer-dist/assets/formatCSSVariablePrefix-KRh9vnZf.js +1 -0
- package/viewer-dist/assets/fortran-fixed-form-1cK5gXa1.js +1 -0
- package/viewer-dist/assets/fortran-free-form-9zh5t3u2.js +1 -0
- package/viewer-dist/assets/fortran-free-form-uHOymLAb.js +1 -0
- package/viewer-dist/assets/fsharp-C37UASp4.js +1 -0
- package/viewer-dist/assets/fsharp-D8ZPuVlk.js +1 -0
- package/viewer-dist/assets/gdresource-LxjHb83i.js +1 -0
- package/viewer-dist/assets/gdscript-C2iVvkL_.js +1 -0
- package/viewer-dist/assets/gdscript-DJFPOtzS.js +1 -0
- package/viewer-dist/assets/gdshader-BpaOOKdG.js +1 -0
- package/viewer-dist/assets/gdshader-kiBtQlv1.js +1 -0
- package/viewer-dist/assets/genie-CV2tkWYe.js +1 -0
- package/viewer-dist/assets/gherkin-DExj1W_8.js +1 -0
- package/viewer-dist/assets/git-commit-BAuDFD-1.js +1 -0
- package/viewer-dist/assets/git-commit-rNeRxB9Y.js +1 -0
- package/viewer-dist/assets/git-rebase-Bh7mDoAc.js +1 -0
- package/viewer-dist/assets/git-rebase-Cpv8mbcu.js +1 -0
- package/viewer-dist/assets/github-dark-C-LZuMrd.js +1 -0
- package/viewer-dist/assets/github-dark-C895GGrm.js +1 -0
- package/viewer-dist/assets/github-dark-default-DXG-b-1a.js +1 -0
- package/viewer-dist/assets/github-dark-default-adAWTKmX.js +1 -0
- package/viewer-dist/assets/github-dark-dimmed-Bx1FflLF.js +1 -0
- package/viewer-dist/assets/github-dark-dimmed-jPx1V1fR.js +1 -0
- package/viewer-dist/assets/github-dark-high-contrast-B_tTalzw.js +1 -0
- package/viewer-dist/assets/github-dark-high-contrast-UN5YjL_Z.js +1 -0
- package/viewer-dist/assets/github-light-B4HDwToD.js +1 -0
- package/viewer-dist/assets/github-light-EUqPIrTm.js +1 -0
- package/viewer-dist/assets/github-light-default-BXViO-2h.js +1 -0
- package/viewer-dist/assets/github-light-default-CfC59JYV.js +1 -0
- package/viewer-dist/assets/github-light-high-contrast-B68TUdTA.js +1 -0
- package/viewer-dist/assets/github-light-high-contrast-C3edEHcK.js +1 -0
- package/viewer-dist/assets/gleam-CSRkHgEL.js +1 -0
- package/viewer-dist/assets/glimmer-js-CIdbWayl.js +1 -0
- package/viewer-dist/assets/glimmer-ts-B16xCo2k.js +1 -0
- package/viewer-dist/assets/glsl-CaPTrB3a.js +1 -0
- package/viewer-dist/assets/glsl-ThNHWs2E.js +1 -0
- package/viewer-dist/assets/gn-CAXYAgV-.js +1 -0
- package/viewer-dist/assets/gnuplot-7GGW24-e.js +1 -0
- package/viewer-dist/assets/go-BrE3Phef.js +1 -0
- package/viewer-dist/assets/go-CFMhVTkq.js +1 -0
- package/viewer-dist/assets/graphql-DAzSVzvB.js +1 -0
- package/viewer-dist/assets/graphql-DEIChqxY.js +1 -0
- package/viewer-dist/assets/groovy-D_Q3n-An.js +1 -0
- package/viewer-dist/assets/groovy-Dj7WCBJM.js +1 -0
- package/viewer-dist/assets/gruvbox-dark-hard-BdGOuxq8.js +1 -0
- package/viewer-dist/assets/gruvbox-dark-hard-C820rvS2.js +1 -0
- package/viewer-dist/assets/gruvbox-dark-medium-BPjhmG05.js +1 -0
- package/viewer-dist/assets/gruvbox-dark-medium-CmygtSMi.js +1 -0
- package/viewer-dist/assets/gruvbox-dark-soft-BJH4XuY9.js +1 -0
- package/viewer-dist/assets/gruvbox-dark-soft-MrdJrrXF.js +1 -0
- package/viewer-dist/assets/gruvbox-light-hard-BC_s9l72.js +1 -0
- package/viewer-dist/assets/gruvbox-light-hard-BkSILF4E.js +1 -0
- package/viewer-dist/assets/gruvbox-light-medium-BAWPOn9u.js +1 -0
- package/viewer-dist/assets/gruvbox-light-medium-DiZUfgdz.js +1 -0
- package/viewer-dist/assets/gruvbox-light-soft-BSMLrYjP.js +1 -0
- package/viewer-dist/assets/gruvbox-light-soft-CRCTnbIj.js +1 -0
- package/viewer-dist/assets/hack-C30D-q0p.js +1 -0
- package/viewer-dist/assets/haml-C1zHJAQt.js +1 -0
- package/viewer-dist/assets/haml-mwfMQlUs.js +1 -0
- package/viewer-dist/assets/handlebars-CEZndQNl.js +1 -0
- package/viewer-dist/assets/handlebars-g-3gLrXt.js +1 -0
- package/viewer-dist/assets/haskell-D8IpX4py.js +1 -0
- package/viewer-dist/assets/haxe-CD8O8Ul0.js +1 -0
- package/viewer-dist/assets/haxe-j5FdAS1V.js +1 -0
- package/viewer-dist/assets/hcl-Dh228itO.js +1 -0
- package/viewer-dist/assets/highlights-B57wCzB5.js +3 -0
- package/viewer-dist/assets/hjson-CxZEssPk.js +1 -0
- package/viewer-dist/assets/hlsl-C3sg_olF.js +1 -0
- package/viewer-dist/assets/hlsl-ajL2FB-w.js +1 -0
- package/viewer-dist/assets/horizon-CE9ld1lL.js +1 -0
- package/viewer-dist/assets/horizon-DUI96lQn.js +1 -0
- package/viewer-dist/assets/horizon-bright-COxh1lHf.js +1 -0
- package/viewer-dist/assets/horizon-bright-DSNQnXHK.js +1 -0
- package/viewer-dist/assets/houston-CsvMBhTu.js +1 -0
- package/viewer-dist/assets/houston-DduE73P7.js +1 -0
- package/viewer-dist/assets/html-DSw1lh5G.js +1 -0
- package/viewer-dist/assets/html-WQKKblVZ.js +1 -0
- package/viewer-dist/assets/html-derivative-CjJKezcp.js +1 -0
- package/viewer-dist/assets/html-derivative-DyzJkWO6.js +1 -0
- package/viewer-dist/assets/http-BjrBtiM6.js +1 -0
- package/viewer-dist/assets/hurl-B4P9s9G3.js +1 -0
- package/viewer-dist/assets/hxml-DPF7XkXa.js +1 -0
- package/viewer-dist/assets/hy-CZbG8q4J.js +1 -0
- package/viewer-dist/assets/imba-DsUTQ-LC.js +1 -0
- package/viewer-dist/assets/index-B0ZrAosS.css +1 -0
- package/viewer-dist/assets/index-CVKGwJkR.js +255 -0
- package/viewer-dist/assets/ini-0B7NLFlx.js +1 -0
- package/viewer-dist/assets/ini-DxURaTxO.js +1 -0
- package/viewer-dist/assets/java-BtIQNnN0.js +1 -0
- package/viewer-dist/assets/java-DxlWrXwe.js +1 -0
- package/viewer-dist/assets/javascript-BzbQS41l.js +1 -0
- package/viewer-dist/assets/javascript-Yelw-5ZN.js +1 -0
- package/viewer-dist/assets/jinja-dRcm23Ea.js +1 -0
- package/viewer-dist/assets/jison-D3aJooqo.js +1 -0
- package/viewer-dist/assets/json-B88Oqtu5.js +1 -0
- package/viewer-dist/assets/json-CaljABEy.js +1 -0
- package/viewer-dist/assets/json5-BR5RXkoi.js +1 -0
- package/viewer-dist/assets/jsonc-CTI_jrid.js +1 -0
- package/viewer-dist/assets/jsonc-dcnCvL0G.js +1 -0
- package/viewer-dist/assets/jsonl-CmCQp5Yx.js +1 -0
- package/viewer-dist/assets/jsonnet-CJTPZ8u_.js +1 -0
- package/viewer-dist/assets/jssm-DXw9l8Rf.js +1 -0
- package/viewer-dist/assets/jsx-D3KKoC5L.js +1 -0
- package/viewer-dist/assets/jsx-hEbJ82HF.js +1 -0
- package/viewer-dist/assets/julia-BCOw4cyx.js +1 -0
- package/viewer-dist/assets/julia-hqywDEUR.js +1 -0
- package/viewer-dist/assets/just-Br47BmIC.js +1 -0
- package/viewer-dist/assets/kanagawa-dragon-BHDhSKDf.js +1 -0
- package/viewer-dist/assets/kanagawa-dragon-Bozd7klA.js +1 -0
- package/viewer-dist/assets/kanagawa-lotus-BmuOG9ZW.js +1 -0
- package/viewer-dist/assets/kanagawa-lotus-NJjGXXql.js +1 -0
- package/viewer-dist/assets/kanagawa-wave-BML5mF2J.js +1 -0
- package/viewer-dist/assets/kanagawa-wave-DsGe2Uqk.js +1 -0
- package/viewer-dist/assets/kdl-CsD5j6eV.js +1 -0
- package/viewer-dist/assets/kotlin-DhhofPvG.js +1 -0
- package/viewer-dist/assets/kusto-C7mF5XQf.js +1 -0
- package/viewer-dist/assets/langs-JgP7EaER.js +2 -0
- package/viewer-dist/assets/laserwave-C_8bwKvT.js +1 -0
- package/viewer-dist/assets/laserwave-DYV0fvJ_.js +1 -0
- package/viewer-dist/assets/latex-B_Ztlc7G.js +1 -0
- package/viewer-dist/assets/latex-Djh9Fg1h.js +1 -0
- package/viewer-dist/assets/lean-CewbzKMR.js +1 -0
- package/viewer-dist/assets/less-B64L-FWb.js +1 -0
- package/viewer-dist/assets/less-GWsDhusf.js +1 -0
- package/viewer-dist/assets/lib-IuaA1a0_.js +9 -0
- package/viewer-dist/assets/light-plus-DVQuIRkW.js +1 -0
- package/viewer-dist/assets/light-plus-FTnIShls.js +1 -0
- package/viewer-dist/assets/liquid-CQNtsgCr.js +1 -0
- package/viewer-dist/assets/llvm-DqHOMS-s.js +1 -0
- package/viewer-dist/assets/loader-D4gJynmd.js +1 -0
- package/viewer-dist/assets/log-BvtJ4bSl.js +1 -0
- package/viewer-dist/assets/log-DSUv6hjM.js +1 -0
- package/viewer-dist/assets/logo-Cluzi2Zq.js +1 -0
- package/viewer-dist/assets/lua-BJObVtAx.js +1 -0
- package/viewer-dist/assets/lua-DjuecEsk.js +1 -0
- package/viewer-dist/assets/luau-VGWVLoqX.js +1 -0
- package/viewer-dist/assets/make-BLT6fICl.js +1 -0
- package/viewer-dist/assets/make-URElk0GJ.js +1 -0
- package/viewer-dist/assets/markdown-CboqBxpY.js +1 -0
- package/viewer-dist/assets/markdown-Cla8Gbs6.js +1 -0
- package/viewer-dist/assets/marko-DPS0EkZ1.js +1 -0
- package/viewer-dist/assets/material-theme-Bm3Qr25_.js +1 -0
- package/viewer-dist/assets/material-theme-IcIb8QNx.js +1 -0
- package/viewer-dist/assets/material-theme-darker-2IIEA8gg.js +1 -0
- package/viewer-dist/assets/material-theme-darker-B_f2vxdL.js +1 -0
- package/viewer-dist/assets/material-theme-lighter-CR2Q-4Hp.js +1 -0
- package/viewer-dist/assets/material-theme-lighter-uhdI0v04.js +1 -0
- package/viewer-dist/assets/material-theme-ocean-BX6hAJ_y.js +1 -0
- package/viewer-dist/assets/material-theme-ocean-CHQ94UKr.js +1 -0
- package/viewer-dist/assets/material-theme-palenight-B5W6OYN7.js +1 -0
- package/viewer-dist/assets/material-theme-palenight-B6DWAotd.js +1 -0
- package/viewer-dist/assets/matlab-D7qyCx1q.js +1 -0
- package/viewer-dist/assets/mdc-C6srEd4p.js +1 -0
- package/viewer-dist/assets/mdx-DQZ5AkYe.js +1 -0
- package/viewer-dist/assets/mermaid-BxpfTIzt.js +1 -0
- package/viewer-dist/assets/min-dark-BSWPekZh.js +1 -0
- package/viewer-dist/assets/min-dark-DECtZcqS.js +1 -0
- package/viewer-dist/assets/min-light-DDpmG2fV.js +1 -0
- package/viewer-dist/assets/min-light-qRIVcaqf.js +1 -0
- package/viewer-dist/assets/mipsasm-BMqwQI7S.js +1 -0
- package/viewer-dist/assets/mojo-fg40_ntQ.js +1 -0
- package/viewer-dist/assets/monokai-BscAjiQZ.js +1 -0
- package/viewer-dist/assets/monokai-CLmrJ-8t.js +1 -0
- package/viewer-dist/assets/moonbit-D9W784E_.js +1 -0
- package/viewer-dist/assets/move-BYnGhZoM.js +1 -0
- package/viewer-dist/assets/narrat-_X_XdTYD.js +1 -0
- package/viewer-dist/assets/nextflow-groovy-1acFxZ7Y.js +1 -0
- package/viewer-dist/assets/nextflow-groovy-C770ykRh.js +1 -0
- package/viewer-dist/assets/nextflow-uA5IJerx.js +1 -0
- package/viewer-dist/assets/nginx-BxRBJ-Af.js +1 -0
- package/viewer-dist/assets/night-owl-DhmEMT88.js +1 -0
- package/viewer-dist/assets/night-owl-eR4AsyAP.js +1 -0
- package/viewer-dist/assets/night-owl-light-C74n5ti-.js +1 -0
- package/viewer-dist/assets/night-owl-light-eJ-hLW7d.js +1 -0
- package/viewer-dist/assets/nim-Dr8hIC6Y.js +1 -0
- package/viewer-dist/assets/nim-ZjzS1dcU.js +1 -0
- package/viewer-dist/assets/nix-IvuFDN5E.js +1 -0
- package/viewer-dist/assets/nord-Cb4Vim4T.js +1 -0
- package/viewer-dist/assets/nord-D4wy7NEP.js +1 -0
- package/viewer-dist/assets/nsis-CjNLYCLg.js +1 -0
- package/viewer-dist/assets/nushell--0fT3PI1.js +1 -0
- package/viewer-dist/assets/objective-c-DMLMCfZd.js +1 -0
- package/viewer-dist/assets/objective-c-D_ECFp-D.js +1 -0
- package/viewer-dist/assets/objective-cpp-BsSzOQcm.js +1 -0
- package/viewer-dist/assets/ocaml-D6dNsUd0.js +1 -0
- package/viewer-dist/assets/ocaml-oSZO9LTw.js +1 -0
- package/viewer-dist/assets/odin-B1RWQWA5.js +1 -0
- package/viewer-dist/assets/one-dark-pro-28TLzoS8.js +1 -0
- package/viewer-dist/assets/one-dark-pro-C6YyR8OD.js +1 -0
- package/viewer-dist/assets/one-light-C0UY_Fh7.js +1 -0
- package/viewer-dist/assets/one-light-D7Lr4KcI.js +1 -0
- package/viewer-dist/assets/openscad-BUDT5pXO.js +1 -0
- package/viewer-dist/assets/org-B3Y3gBCc.js +1 -0
- package/viewer-dist/assets/pascal-4ZHwLPI5.js +1 -0
- package/viewer-dist/assets/perl-Di9CLCS0.js +1 -0
- package/viewer-dist/assets/perl-sgZsTtaf.js +1 -0
- package/viewer-dist/assets/php-D9QpVhjP.js +1 -0
- package/viewer-dist/assets/php-DXPvgw5o.js +1 -0
- package/viewer-dist/assets/pierre-dark-CpLgRqie.js +1 -0
- package/viewer-dist/assets/pierre-dark-fPlffE7i.js +1 -0
- package/viewer-dist/assets/pierre-dark-protanopia-deuteranopia-B35FxJx-.js +1 -0
- package/viewer-dist/assets/pierre-dark-protanopia-deuteranopia-BmjibgrW.js +1 -0
- package/viewer-dist/assets/pierre-dark-soft-Cng2SYKc.js +1 -0
- package/viewer-dist/assets/pierre-dark-soft-kZQmAZld.js +1 -0
- package/viewer-dist/assets/pierre-dark-tritanopia-CpjhbsIL.js +1 -0
- package/viewer-dist/assets/pierre-dark-tritanopia-DneQ5i7L.js +1 -0
- package/viewer-dist/assets/pierre-dark-vibrant-BUK9Y-N_.js +1 -0
- package/viewer-dist/assets/pierre-dark-vibrant-CpQYzh95.js +1 -0
- package/viewer-dist/assets/pierre-light-BvcXQJIj.js +1 -0
- package/viewer-dist/assets/pierre-light-CoaEpmwp.js +1 -0
- package/viewer-dist/assets/pierre-light-protanopia-deuteranopia-0fSaH845.js +1 -0
- package/viewer-dist/assets/pierre-light-protanopia-deuteranopia-Cd5nk0bp.js +1 -0
- package/viewer-dist/assets/pierre-light-soft-BvU23vks.js +1 -0
- package/viewer-dist/assets/pierre-light-soft-lWLdNTOI.js +1 -0
- package/viewer-dist/assets/pierre-light-tritanopia-BSHccQzI.js +1 -0
- package/viewer-dist/assets/pierre-light-tritanopia-CEbqgOJL.js +1 -0
- package/viewer-dist/assets/pierre-light-vibrant-BgMZEwQI.js +1 -0
- package/viewer-dist/assets/pierre-light-vibrant-D80Fkn33.js +1 -0
- package/viewer-dist/assets/pkl-ot-7Btpt.js +1 -0
- package/viewer-dist/assets/plastic-B2V_PDVk.js +1 -0
- package/viewer-dist/assets/plastic-DQwYfKfQ.js +1 -0
- package/viewer-dist/assets/plsql-DGHpHOYJ.js +1 -0
- package/viewer-dist/assets/po-BiJDBrnU.js +1 -0
- package/viewer-dist/assets/poimandres-DB9-pI6r.js +1 -0
- package/viewer-dist/assets/poimandres-DRFjx7u4.js +1 -0
- package/viewer-dist/assets/polar-C7UOKdEL.js +1 -0
- package/viewer-dist/assets/postcss-D_Wz94rJ.js +1 -0
- package/viewer-dist/assets/postcss-e3XvZOFQ.js +1 -0
- package/viewer-dist/assets/powerquery-DNMTfnFr.js +1 -0
- package/viewer-dist/assets/powershell-CItYMEtV.js +1 -0
- package/viewer-dist/assets/powershell-DyPZnz5v.js +1 -0
- package/viewer-dist/assets/preload-helper-BZ1Pz5am.js +1 -0
- package/viewer-dist/assets/prisma-DMgNhnYS.js +1 -0
- package/viewer-dist/assets/prolog-iXnhIJG7.js +1 -0
- package/viewer-dist/assets/proto-DB4EqR-F.js +1 -0
- package/viewer-dist/assets/pug-BlofpNpK.js +1 -0
- package/viewer-dist/assets/pug-nGRwXpob.js +1 -0
- package/viewer-dist/assets/puppet-CDv2pdJW.js +1 -0
- package/viewer-dist/assets/purescript-9MfHhQsQ.js +1 -0
- package/viewer-dist/assets/python-CzFU0dpx.js +1 -0
- package/viewer-dist/assets/python-ORI17Sev.js +1 -0
- package/viewer-dist/assets/qml-BxleM7bJ.js +1 -0
- package/viewer-dist/assets/qmldir-DCQb3MpD.js +1 -0
- package/viewer-dist/assets/qss-Fe1Jh2GI.js +1 -0
- package/viewer-dist/assets/r-DWzjseEo.js +1 -0
- package/viewer-dist/assets/r-Dr1JUpHl.js +1 -0
- package/viewer-dist/assets/racket-DcIDlBhZ.js +1 -0
- package/viewer-dist/assets/raku-B6hKIqfP.js +1 -0
- package/viewer-dist/assets/raku-BtFKomnU.js +1 -0
- package/viewer-dist/assets/razor-UAq-8THt.js +1 -0
- package/viewer-dist/assets/rbs-C0MpOrj4.js +1 -0
- package/viewer-dist/assets/red-CYlAq2b0.js +1 -0
- package/viewer-dist/assets/red-CqYzoXtd.js +1 -0
- package/viewer-dist/assets/reg-CRGYupPL.js +1 -0
- package/viewer-dist/assets/regexp-B4pBNbU3.js +1 -0
- package/viewer-dist/assets/regexp-BWpGejPw.js +1 -0
- package/viewer-dist/assets/rel-BtDbiS_P.js +1 -0
- package/viewer-dist/assets/riscv-Ckw8ddFX.js +1 -0
- package/viewer-dist/assets/rolldown-runtime-Dd_uD5pT.js +1 -0
- package/viewer-dist/assets/ron-VUp2lXgN.js +1 -0
- package/viewer-dist/assets/rose-pine-C3zjVKxG.js +1 -0
- package/viewer-dist/assets/rose-pine-aMsaMD1D.js +1 -0
- package/viewer-dist/assets/rose-pine-dawn-8PwUyIlP.js +1 -0
- package/viewer-dist/assets/rose-pine-dawn-C72QYfqa.js +1 -0
- package/viewer-dist/assets/rose-pine-moon-CSM8ewhO.js +1 -0
- package/viewer-dist/assets/rose-pine-moon-DO-qXg-I.js +1 -0
- package/viewer-dist/assets/rosmsg-CAekHB0j.js +1 -0
- package/viewer-dist/assets/rst-DT-C-5fA.js +1 -0
- package/viewer-dist/assets/ruby-B6sU6EpJ.js +1 -0
- package/viewer-dist/assets/ruby-BwIxDKXu.js +1 -0
- package/viewer-dist/assets/rust-DBZE5Si3.js +1 -0
- package/viewer-dist/assets/rust-tUOVui2B.js +1 -0
- package/viewer-dist/assets/sas-BowjnAvi.js +1 -0
- package/viewer-dist/assets/sass-DXrisJhu.js +1 -0
- package/viewer-dist/assets/scala-Dcd77NNm.js +1 -0
- package/viewer-dist/assets/scala-o2NiCLJc.js +1 -0
- package/viewer-dist/assets/scheme-DQCgrYNe.js +1 -0
- package/viewer-dist/assets/scss-CWs8DVSa.js +1 -0
- package/viewer-dist/assets/scss-Dec6wfVg.js +1 -0
- package/viewer-dist/assets/sdbl-CpzYUp7e.js +1 -0
- package/viewer-dist/assets/sdbl-DFPhMlBm.js +1 -0
- package/viewer-dist/assets/shaderlab-DY7g_Ava.js +1 -0
- package/viewer-dist/assets/shellscript-BiGZg9Om.js +1 -0
- package/viewer-dist/assets/shellscript-CqHdAlCp.js +1 -0
- package/viewer-dist/assets/shellsession-DDrivR0a.js +1 -0
- package/viewer-dist/assets/shiki-BYYByAlk.js +2 -0
- package/viewer-dist/assets/slack-dark-DnToyrRv.js +1 -0
- package/viewer-dist/assets/slack-dark-Dtzi51su.js +1 -0
- package/viewer-dist/assets/slack-ochin-B2OO5cIa.js +1 -0
- package/viewer-dist/assets/slack-ochin-Bb7oPExa.js +1 -0
- package/viewer-dist/assets/smalltalk-BHpQb5nM.js +1 -0
- package/viewer-dist/assets/smithy-Dgaz7aur.js +1 -0
- package/viewer-dist/assets/snazzy-light-4G7pJPwS.js +1 -0
- package/viewer-dist/assets/snazzy-light-DXgiwzKu.js +1 -0
- package/viewer-dist/assets/solarized-dark-BKOT3ICq.js +1 -0
- package/viewer-dist/assets/solarized-dark-b97czJOk.js +1 -0
- package/viewer-dist/assets/solarized-light--Lk5pOfE.js +1 -0
- package/viewer-dist/assets/solarized-light-DFPxpIYQ.js +1 -0
- package/viewer-dist/assets/solidity-Bj7E1mRn.js +1 -0
- package/viewer-dist/assets/soy-CUUUw2U6.js +1 -0
- package/viewer-dist/assets/sparql-Dy5Sx-zJ.js +1 -0
- package/viewer-dist/assets/splunk-BC2Px7Mm.js +1 -0
- package/viewer-dist/assets/sql-BOsskAmu.js +1 -0
- package/viewer-dist/assets/sql-CNu3Or2W.js +1 -0
- package/viewer-dist/assets/ssh-config-BgfXC-Er.js +1 -0
- package/viewer-dist/assets/stata-Dj4sbAEx.js +1 -0
- package/viewer-dist/assets/stream-tokenizer-a_hv0fYK.js +4 -0
- package/viewer-dist/assets/stylus-BOYZFyl7.js +1 -0
- package/viewer-dist/assets/stylus-LiTfbrWi.js +1 -0
- package/viewer-dist/assets/surrealql-NoXzmj18.js +1 -0
- package/viewer-dist/assets/svelte-BaCIHHWd.js +1 -0
- package/viewer-dist/assets/swift-CpxeRS9H.js +1 -0
- package/viewer-dist/assets/swift-DQ24oLw9.js +1 -0
- package/viewer-dist/assets/synthwave-84-BJJFg-sc.js +1 -0
- package/viewer-dist/assets/synthwave-84-nFMaYfgc.js +1 -0
- package/viewer-dist/assets/system-verilog-CIGW6CHD.js +1 -0
- package/viewer-dist/assets/system-verilog-Dp2k_mze.js +1 -0
- package/viewer-dist/assets/systemd-BxMlprV5.js +1 -0
- package/viewer-dist/assets/talonscript-CohzipZa.js +1 -0
- package/viewer-dist/assets/tasl-DMoTqEGO.js +1 -0
- package/viewer-dist/assets/tcl-CZd0xW_V.js +1 -0
- package/viewer-dist/assets/templ-BfgLc4ra.js +1 -0
- package/viewer-dist/assets/terraform-DswuEJGm.js +1 -0
- package/viewer-dist/assets/tex-C9L8xJex.js +1 -0
- package/viewer-dist/assets/tex-CeakZqzU.js +1 -0
- package/viewer-dist/assets/themes-DP0gt5jG.js +2 -0
- package/viewer-dist/assets/tokyo-night-DvpptEDd.js +1 -0
- package/viewer-dist/assets/tokyo-night-oM2G3aXe.js +1 -0
- package/viewer-dist/assets/toml-CcmNWLt0.js +1 -0
- package/viewer-dist/assets/ts-tags-DLz2GTd3.js +1 -0
- package/viewer-dist/assets/tsv-sltzmVWM.js +1 -0
- package/viewer-dist/assets/tsx-5f3ulCja.js +1 -0
- package/viewer-dist/assets/tsx-BOvsFOI6.js +1 -0
- package/viewer-dist/assets/turtle-B2uMLKuz.js +1 -0
- package/viewer-dist/assets/turtle-CcN57yC0.js +1 -0
- package/viewer-dist/assets/twig-BuizuR2K.js +1 -0
- package/viewer-dist/assets/twig-p9meEoSL.js +1 -0
- package/viewer-dist/assets/typescript-Utq2Cl8c.js +1 -0
- package/viewer-dist/assets/typescript-j_1H8WHN.js +1 -0
- package/viewer-dist/assets/typespec-BGhR2SqG.js +1 -0
- package/viewer-dist/assets/typst-qZ7a-KdK.js +1 -0
- package/viewer-dist/assets/unwrapDefault-ByDmBtHB.js +1 -0
- package/viewer-dist/assets/v-DBj4K9d_.js +1 -0
- package/viewer-dist/assets/vala-zf12oZj6.js +1 -0
- package/viewer-dist/assets/vb-3nVziYZS.js +1 -0
- package/viewer-dist/assets/vb-Dcr14nCw.js +1 -0
- package/viewer-dist/assets/verilog-DUw2aqD4.js +1 -0
- package/viewer-dist/assets/verilog-kL8Dwv27.js +1 -0
- package/viewer-dist/assets/vesper-C1rBZbON.js +1 -0
- package/viewer-dist/assets/vesper-DdrHHSXu.js +1 -0
- package/viewer-dist/assets/vhdl-BroJfC0k.js +1 -0
- package/viewer-dist/assets/viml-DvXPmvsu.js +1 -0
- package/viewer-dist/assets/vitesse-black-Sqvrs2Sw.js +1 -0
- package/viewer-dist/assets/vitesse-black-fwtXNY1n.js +1 -0
- package/viewer-dist/assets/vitesse-dark-BWf_ZQtP.js +1 -0
- package/viewer-dist/assets/vitesse-dark-BZCL-v6S.js +1 -0
- package/viewer-dist/assets/vitesse-light-Cqenv4Qv.js +1 -0
- package/viewer-dist/assets/vitesse-light-VbXTXTou.js +1 -0
- package/viewer-dist/assets/vue-html-CGMs_6qn.js +1 -0
- package/viewer-dist/assets/vue-qH43U_rv.js +1 -0
- package/viewer-dist/assets/vue-vine-6XI2pIvQ.js +1 -0
- package/viewer-dist/assets/vyper-CgoNMtux.js +1 -0
- package/viewer-dist/assets/wasm-BnjxR4X6.js +1 -0
- package/viewer-dist/assets/wasm-ByWQv1Qj.js +1 -0
- package/viewer-dist/assets/wenyan-C8pVoKbM.js +1 -0
- package/viewer-dist/assets/wgsl-BsKzXJz4.js +1 -0
- package/viewer-dist/assets/wikitext-ClFFjSW2.js +1 -0
- package/viewer-dist/assets/wit-DdvCle-K.js +1 -0
- package/viewer-dist/assets/wolfram-DLL8P-h_.js +1 -0
- package/viewer-dist/assets/xml-CoDIzWF0.js +1 -0
- package/viewer-dist/assets/xml-WY0zc4PG.js +1 -0
- package/viewer-dist/assets/xsl-ChYNfH-b.js +1 -0
- package/viewer-dist/assets/xsl-Czhm44Ae.js +1 -0
- package/viewer-dist/assets/yaml-CxbubiML.js +1 -0
- package/viewer-dist/assets/yaml-DijMHRDA.js +1 -0
- package/viewer-dist/assets/zenscript-BnlCZFoB.js +1 -0
- package/viewer-dist/assets/zig-B7sSDI6F.js +1 -0
- package/viewer-dist/assets/zig-VWdiCTxG.js +1 -0
- package/viewer-dist/index.html +77 -0
package/guide.md
ADDED
|
@@ -0,0 +1,251 @@
|
|
|
1
|
+
# Productdoc documents
|
|
2
|
+
|
|
3
|
+
Create a general-purpose visual document that explains what exists, plans future work, or reviews what changed. Lead with the reader's question and the reasoning they need, not a code diff. Start with familiar screens, actions, or workflows when available; otherwise use involved services, messages, and state. Code supports the story rather than setting its outline.
|
|
4
|
+
|
|
5
|
+
A document is a directory at `.diffmap/specs/<short-kebab-case-name>/`. Reuse the effort's existing directory and update it as understanding, plans, and work change; do not create separate explanation, plan, and review copies. Keep existing paths during migration. Commit documents with the relevant work and check source paths before referencing them.
|
|
6
|
+
|
|
7
|
+
**Migration:** productdoc succeeds Diffmap. The `generate-diffmap` and `generate-product-doc` skills coexist temporarily; reuse existing documents without migrating their paths. The package is `product-doc`, with executable `product-doc`. The existing sharing host remains diffmap.dev until productdoc.dev supports those links.
|
|
8
|
+
|
|
9
|
+
## Match the document to the question
|
|
10
|
+
|
|
11
|
+
- **Explain existing behavior:** lead with what happens today, why, and who owns the outcome. Show the relevant failure path as well as the successful one. Link inspected evidence and label uncertainty. An explanation without proposed changes needs no artificial implementation phases.
|
|
12
|
+
- **Plan future work:** lead with the problem, intended outcome, alternatives, and decision. Put the overview in `README.md`, then put each small, independent or commit-sized change on its own numbered page: **one small change per page**. Split by a coherent change someone can review and land, not by source file. Link dependencies instead of repeating the whole plan. Explain Today, Proposed, reasoning, and verification for each phase.
|
|
13
|
+
- **Review changes made:** lead with the observable difference and its reason. Show actual before/after behavior, preview prose changes as well as code, and distinguish local work from released behavior. Update the existing phase pages. Follow the commit-reference rules only for real commits.
|
|
14
|
+
|
|
15
|
+
A request to explain, plan, or preview does not authorize implementing the proposal. Label unbuilt behavior, illustrative patches, and mockups. A plan's diagram is not proof of executed behavior.
|
|
16
|
+
|
|
17
|
+
## Draw the reasoning
|
|
18
|
+
|
|
19
|
+
Use a diagram when readers would otherwise assemble a flow, owner, dependency, or changed relationship from paragraphs. Name nodes and arrows at the reader's level, include the failure or alternative that changes the decision, and put the picture beside that decision. A graph of function names is not a product explanation.
|
|
20
|
+
|
|
21
|
+
Use a flow diagram for responsibilities and dependencies, a services diagram for messages and state across services, and a call-stack diff for a changed decision within an operation. Keep only calls that explain the consequence and label unlinked pseudocode as illustrative. Show screenshots for visible states and recordings for timing or interaction; inspect them before including them.
|
|
22
|
+
|
|
23
|
+
Preview prose changes too, including skill instructions, README text, and policies. A `diff` fence shows old/new wording; add the readable result when it helps judge meaning. Label proposed patches rather than presenting them as actual repository changes. Keep source detail behind links unless it changes the reader's decision.
|
|
24
|
+
|
|
25
|
+
**Settle scope first.** Inspect the relevant evidence before writing; for repository-backed explanations, read the code that owns the behavior. When the design, scope, or phase split is unclear, check with the user before writing much: offer the options and your pick.
|
|
26
|
+
|
|
27
|
+
## Serve and share
|
|
28
|
+
|
|
29
|
+
Run from the repo root:
|
|
30
|
+
|
|
31
|
+
```sh
|
|
32
|
+
npx product-doc validate .diffmap/specs/<name>/ # check after writing or editing, even if already served
|
|
33
|
+
npx product-doc list # reuse the URL if this spec is already served
|
|
34
|
+
npx product-doc serve .diffmap/specs/<name>/
|
|
35
|
+
npx product-doc share .diffmap/specs/<name>/ # only when asked; prints https://diffmap.dev/g/<id>
|
|
36
|
+
```
|
|
37
|
+
|
|
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
|
+
|
|
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
|
+
|
|
42
|
+
## Shape
|
|
43
|
+
|
|
44
|
+
Write for someone who needs to understand the system or decision quickly. Start from a recognizable action, workflow, service responsibility, or outcome, then descend into implementation only as far as the reader needs. Explain existing behavior without inventing changes; reserve Today/Proposed comparisons and implementation phases for plans or reviews.
|
|
45
|
+
|
|
46
|
+
**Pages.** The reader sees one page at a time, with a list of pages beside it and a link to the next page below it.
|
|
47
|
+
|
|
48
|
+
```text
|
|
49
|
+
.diffmap/specs/<name>/
|
|
50
|
+
README.md cover: problem overview, solution overview, goals, non-goals, References
|
|
51
|
+
01-<phase-slug>.md one page per phase, in order
|
|
52
|
+
02-<phase-slug>.md
|
|
53
|
+
media/<phase-slug>/ screenshots and recordings for that page
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
- `README.md` is the cover; its first heading is the document title shown by the viewer, not a generic product label or the directory name. Keep title and URL slug separate. Let the content decide what each section needs, and don't repeat the cover on other pages.
|
|
57
|
+
- Every other page is `NN-<slug>.md`, numbered from `01` with two digits. The number sets the page's place in the spec; the slug is its URL, so renumbering keeps links and comments. To insert a page, `git mv` the pages after it to new numbers. `validate` rejects a Markdown file without a number.
|
|
58
|
+
- Each page is readable on its own by someone who read the cover and skimmed the pages before it. Open it with a sentence or two that says what earlier pages built that it relies on, linked, as in "[Phase 1](01-sessions-table.md) added the `sessions` table." Then say what this page changes. Define a term on the page that introduces it, and link back to that page when a later page uses it.
|
|
59
|
+
- Link between pages with relative links to the file, as in `[Phase 2](02-write-through.md#tests)`. They open in productdoc and on GitHub.
|
|
60
|
+
|
|
61
|
+
**Phases.** Keep each small enough to commit alone. A phase's page starts with its title as the page's first heading: plain when planned, ⏳ in progress, and ✅ done, so the page list shows progress. After its opening context, give a short **Today** and **Proposed** from the client's view, then explain it however suits the change: a new flow might want a diagram and a call stack, a refactor a call stack diff, a dependency bump a sentence or two. Match the length to the change, and say each thing once, where it belongs. A spec explains the change; it is not a task tracker. End each phase's page with its `changes` fence, after the walkthrough, not right after Today and Proposed; leave it empty until the phase is committed. The page's Diff button opens that commit.
|
|
62
|
+
|
|
63
|
+
**Visuals.** Diagrams, call stacks, and code often explain a change better than paragraphs, so reach for one when prose gets long. Add one only when it shows the reader something they need, not to fill a slot.
|
|
64
|
+
|
|
65
|
+
The views fit one model: services receive messages, update their state, and send messages on. Each view looks between services or inside one, at every path or at one message's trace:
|
|
66
|
+
|
|
67
|
+
| | Every path | One message |
|
|
68
|
+
| ------------------ | ------------------------------------------------ | ------------------------------------------------------------------ |
|
|
69
|
+
| Between services | `mermaid` flowchart: who exists, who owns what | `services`: a message crossing services, with the state it changes |
|
|
70
|
+
| Inside one service | Pseudocode and types: its state, payloads, logic | `callstack`: how it turns one message into a result |
|
|
71
|
+
|
|
72
|
+
Use `services` when the parts keep state, run at the same time, or fan out; use a call stack when they are function calls that return, branch, or return early. In a `services` diagram, state is what you would find inside a service if you paused between steps; a result passed back is a reply event, not state. To explain a step, put a `>` note under its event, its update, or a service name on its own line. Mermaid sequence and state diagrams are lighter options. If a view needs more than about 7 services, collapse some and explain them separately.
|
|
73
|
+
|
|
74
|
+
- To show a change, add `diff` after `mermaid` or `services` and start each line with `-` (Today only), `+` (Proposed only), or a space (both), as in a call stack. For code, use a `diff` fence.
|
|
75
|
+
- Title Mermaid diagrams with `[Title]` after the language, as in `mermaid diff [Invalid records stop before storage]`. A `services` fence uses `start "caption"` before its first step as the title of the whole diagram, with a `>` line under it that summarizes the full process in a few sentences; caption each step with what happens.
|
|
76
|
+
- Label nodes and arrows with real names, and link existing source with `%% ref` directives.
|
|
77
|
+
|
|
78
|
+
**Call stacks.** Write rows as data flow, `result = function(inputs)`, with `return` rows where they matter. Mark rows `-` (original), `+` (change), or a space (unchanged); a diff compares the same function before and after. Nest calls with `├──` and `└──`. Link real functions with source references; an unlinked helper is pseudocode, not a promised API. Keep stacks to about a dozen rows, splitting deep flows into an overview and a stack per changed callee.
|
|
79
|
+
|
|
80
|
+
**Code.** Keep fences short and on the point the paragraph makes; elide unchanged code with `// ...`. Highlight lines with `{2-3}` after the language (or rows with `{3-4}` after `callstack`), and explain with notes at the bottom instead of long comments: `// [!note L3 symbol] text` or `// [!note L3-L5 symbol] text` for a name on specific lines, `// [!note symbol] text` for a fence-wide name, and `// [!note L3-L5] text` for a highlighted snippet. Symbol notes underline only the first whole-word match on each eligible line. Line numbers count from the top of the fence. Call stacks take the same notes with `#`.
|
|
81
|
+
|
|
82
|
+
**Links.** Link existing source with [references](#source-references); write planned symbols as plain text.
|
|
83
|
+
|
|
84
|
+
**Screenshots and recordings.** When a phase changes something a person sees, show it; [Capture UI changes](#capture-ui-changes) says which kind 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
|
+
|
|
86
|
+
```md
|
|
87
|
+
:::gallery side-by-side
|
|
88
|
+

|
|
89
|
+

|
|
90
|
+
:::
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## Prose
|
|
94
|
+
|
|
95
|
+
Follow Orwell's six rules from "Politics and the English Language" in all prose, comments, and diagram labels. Code names are not jargon.
|
|
96
|
+
|
|
97
|
+
## Example phase
|
|
98
|
+
|
|
99
|
+
This example page, `02-validate-request-input.md`, uses illustrative files and a commit SHA, not Diffmap source paths. Its change crosses a few layers, so it uses several views; a smaller phase needs fewer.
|
|
100
|
+
|
|
101
|
+
````md
|
|
102
|
+
# ⏳ Phase 2: Validate request input
|
|
103
|
+
|
|
104
|
+
[Phase 1](01-record-errors.md) gave every response an `error` field. This phase fills it when a record is invalid.
|
|
105
|
+
|
|
106
|
+
**Today**
|
|
107
|
+
|
|
108
|
+
The handler passes records straight to the service. A client that sends an empty name gets a success response, and the bad record surfaces later as a storage error the client never sees, so they keep sending bad input.
|
|
109
|
+
|
|
110
|
+
**Proposed**
|
|
111
|
+
|
|
112
|
+
A client that sends an empty name gets an error naming the `name` field, so they can fix the request right away. Bulk import in [Phase 3](03-bulk-import.md) needs every saved record to be valid, so this check comes first.
|
|
113
|
+
|
|
114
|
+
From the client's side, the same empty-name request now fails at once:
|
|
115
|
+
|
|
116
|
+
```ts
|
|
117
|
+
const response = await client.saveRecord({ name: "" });
|
|
118
|
+
// before: { ok: true }
|
|
119
|
+
// after: { ok: false, error: "name must not be empty" }
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Today every record reaches storage. In the proposed flow, a valid record follows the same save path, but an invalid one returns an error before storage. The unlinked `validateInput` helper is pseudocode, not a proposed public API:
|
|
123
|
+
|
|
124
|
+
```mermaid diff [Invalid records stop before storage]
|
|
125
|
+
flowchart LR
|
|
126
|
+
- A[requestHandler] -->|record| B[existingService]
|
|
127
|
+
+ A[requestHandler] -->|record| V[validateInput]
|
|
128
|
+
+ V -->|valid record| B[existingService]
|
|
129
|
+
+ V -->|invalid record| E[Return name error]
|
|
130
|
+
B -->|record| D[Storage]
|
|
131
|
+
%% ref node:A [[src/request.ts#requestHandler]]
|
|
132
|
+
%% ref node:B [[src/service.ts#existingService]]
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
The call stack shows how the validation result controls the return path:
|
|
136
|
+
|
|
137
|
+
```callstack
|
|
138
|
+
response = requestHandler(record) [[src/request.ts#requestHandler]]
|
|
139
|
+
-└── return existingService(record) [[src/service.ts#existingService]]
|
|
140
|
+
+├── error = validateInput(record) # reject empty names
|
|
141
|
+
+├── if error: return error
|
|
142
|
+
+├── result = existingService(record) [[src/service.ts#existingService]]
|
|
143
|
+
+│ ├── storage.save(record)
|
|
144
|
+
+│ └── return { ok: true }
|
|
145
|
+
+└── return result
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
In code, the handler returns before the existing save:
|
|
149
|
+
|
|
150
|
+
```ts {2-3}
|
|
151
|
+
function requestHandler(record: RecordInput) {
|
|
152
|
+
const error = validateInput(record);
|
|
153
|
+
if (error) return error;
|
|
154
|
+
return existingService(record);
|
|
155
|
+
}
|
|
156
|
+
// [!note validateInput] Returns an error when `name` is blank, otherwise undefined.
|
|
157
|
+
// [!note L3] Storage never sees an invalid record.
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
The new check:
|
|
161
|
+
|
|
162
|
+
```ts
|
|
163
|
+
function validateInput(record: RecordInput) {
|
|
164
|
+
if (record.name.trim() === "")
|
|
165
|
+
return { ok: false, error: "name must not be empty" };
|
|
166
|
+
return undefined;
|
|
167
|
+
}
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
```changes
|
|
171
|
+
|
|
172
|
+
```
|
|
173
|
+
````
|
|
174
|
+
|
|
175
|
+
## When a phase is complete
|
|
176
|
+
|
|
177
|
+
Before starting the next phase:
|
|
178
|
+
|
|
179
|
+
1. Commit the code. If the phase took several commits, use `<base>..<head>` wherever these steps say SHA.
|
|
180
|
+
2. Put that SHA in the phase's `changes` fence at the end of the phase. It renders the phase's summary card. Under the SHA, list the files a reviewer should read, one path per line, in the order to read them: usually the client-facing entry point first, then down the layers. Then add an `ignore:` line and list every other changed file under it: files that need no thought, such as lockfiles, generated code, snapshots, fixtures, and mechanical renames. The card folds them under "N other files". Every changed file goes in one list or the other; don't explain ignored files in the prose.
|
|
181
|
+
3. Point every reference the phase changed at the commit: stack rows, `%% ref` directives, and prose.
|
|
182
|
+
4. Update diagrams, call stacks, and pseudocode to match what was built, and mark the page's title ✅.
|
|
183
|
+
5. Commit the spec update separately; it names the code commit's SHA.
|
|
184
|
+
6. Restart `serve`; it checks commit references at startup, and its `warnings` name changed files that a `changes` fence leaves off both lists. Add each one to a list.
|
|
185
|
+
|
|
186
|
+
The example phase keeps its walkthrough, with references pointing at the commit, and ends with:
|
|
187
|
+
|
|
188
|
+
````md
|
|
189
|
+
```callstack
|
|
190
|
+
response = requestHandler(record) [[a1b2c3d:src/request.ts#L8-L20]]
|
|
191
|
+
-└── return existingService(record) [[src/service.ts#existingService]]
|
|
192
|
+
+├── error = validateInput(record) [[a1b2c3d:src/validate.ts#L1-L9]]
|
|
193
|
+
+├── if error: return error
|
|
194
|
+
+├── result = existingService(record) [[src/service.ts#existingService]]
|
|
195
|
+
+│ ├── storage.save(record)
|
|
196
|
+
+│ └── return { ok: true }
|
|
197
|
+
+└── return result
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
```changes
|
|
201
|
+
a1b2c3d
|
|
202
|
+
src/request.ts
|
|
203
|
+
src/validate.ts
|
|
204
|
+
|
|
205
|
+
ignore:
|
|
206
|
+
src/request.test.ts
|
|
207
|
+
```
|
|
208
|
+
````
|
|
209
|
+
|
|
210
|
+
## Capture UI changes
|
|
211
|
+
|
|
212
|
+
When a phase changes a UI, 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.
|
|
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.
|
|
223
|
+
|
|
224
|
+
## Source references
|
|
225
|
+
|
|
226
|
+
Paths are relative to the repo root.
|
|
227
|
+
|
|
228
|
+
- `[[path/to/file.ts#symbolName]]` links a TypeScript or JavaScript declaration; qualify ambiguous ones, as in `[[src/store.ts#Store.save]]`.
|
|
229
|
+
- `[[path]]` links a file; `[[path#L12-L30]]` a line range.
|
|
230
|
+
- `[[<sha>:path#L12-L30]]` links lines in a commit, or `<base>..<head>` for a phase over several commits, where `<base>` is the commit before the first. Lines are numbered after the commit, so deleted lines cannot be linked. Find them with `git show <sha> -- <path>` and `git show <sha>:<path> | nl -ba`.
|
|
231
|
+
- A reference without a commit opens that file's uncommitted changes, or the current file when it has none. A shared gist opens the file as it was when shared.
|
|
232
|
+
- In prose, references render as clickable inline code; wrap one in backticks to show the syntax.
|
|
233
|
+
- In Mermaid, `%% ref node:<id> [[reference]]` links a node or participant and `%% ref edge:<index> [[reference]]` an edge or message, counting from zero in declaration order. Use one directive per target, with several references when needed.
|
|
234
|
+
|
|
235
|
+
Fences: `mermaid` draws a diagram, `services` an animated diagram of services, their state, and the events between them (add `diff` after either to mark lines `-` or `+`), `callstack` stack rows, `changes` a commit or range summary (empty for uncommitted changes) with the files to review listed under it, and `html` trusted HTML you wrote. Other languages are pseudocode and types, with optional `{…}` highlights and `[!note …]` lines. `[Title]` after the language, as in ` ```callstack [Request flow] `, titles a call stack, code fence, or Mermaid diagram.
|
|
236
|
+
|
|
237
|
+
## Feedback
|
|
238
|
+
|
|
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, open an issue on the existing GitHub repo. Search first, and comment on a matching issue instead of opening a duplicate:
|
|
240
|
+
|
|
241
|
+
```sh
|
|
242
|
+
gh issue list --repo tanishqkancharla/diffmap --search "<keywords>" --state all
|
|
243
|
+
gh issue create --repo tanishqkancharla/diffmap --title "<short summary>" --body "<details>"
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
Say what you did, what you expected, and what happened, with the productdoc version (`npx product-doc --version`) and the smallest Markdown that shows the problem. Issues are public, so leave out private code, file contents, paths, and gist links unless the user agrees. Give the user the issue URL.
|
|
247
|
+
|
|
248
|
+
## Look up the rest
|
|
249
|
+
|
|
250
|
+
- Full reference and fence syntax → [productdoc README](https://github.com/tanishqkancharla/diffmap#link-call-stacks-to-source-changes)
|
|
251
|
+
- Worked examples → [annotations](https://github.com/tanishqkancharla/diffmap/blob/main/fixtures/annotations/README.md), [diagrams](https://github.com/tanishqkancharla/diffmap/blob/main/fixtures/references/README.md), [services](https://github.com/tanishqkancharla/diffmap/blob/main/fixtures/services/README.md), and [media](https://github.com/tanishqkancharla/diffmap/blob/main/fixtures/media/README.md) fixtures
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import { type Rev } from "./changes.js";
|
|
2
|
+
/**
|
|
3
|
+
* A file, symbol, or line range. With a commit `rev`, the panel opens that
|
|
4
|
+
* commit's changes and line numbers refer to the file after the commit.
|
|
5
|
+
* Without one, it opens uncommitted changes, or the current file when the
|
|
6
|
+
* file has none.
|
|
7
|
+
*/
|
|
8
|
+
type FileReference = {
|
|
9
|
+
kind: "file";
|
|
10
|
+
rev?: Rev;
|
|
11
|
+
path: string;
|
|
12
|
+
symbol?: string;
|
|
13
|
+
start?: number;
|
|
14
|
+
end?: number;
|
|
15
|
+
};
|
|
16
|
+
/** Every file in a rev, such as a changes card's Review button. */
|
|
17
|
+
type ChangesReference = {
|
|
18
|
+
kind: "changes";
|
|
19
|
+
rev: Rev;
|
|
20
|
+
path?: string;
|
|
21
|
+
};
|
|
22
|
+
export type SourceReference = FileReference | ChangesReference;
|
|
23
|
+
export type SourceAnnotation = {
|
|
24
|
+
text: string;
|
|
25
|
+
references: SourceReference[];
|
|
26
|
+
/** Source panel title while selected, such as a call stack row without its tree. */
|
|
27
|
+
title?: string;
|
|
28
|
+
};
|
|
29
|
+
export declare function parseCallStack(source: string): SourceAnnotation[];
|
|
30
|
+
/** A call stack row's change mark, tree prefix, and the call it describes. */
|
|
31
|
+
export declare function callStackRow(text: string): {
|
|
32
|
+
sign: string;
|
|
33
|
+
tree: string;
|
|
34
|
+
description: string;
|
|
35
|
+
};
|
|
36
|
+
export declare function parseAnnotation(line: string): SourceAnnotation;
|
|
37
|
+
export declare function parseReference(value: string): SourceReference | undefined;
|
|
38
|
+
/** Short label; pass `basename` for inline prose. */
|
|
39
|
+
export declare function referenceLabel(reference: SourceReference, basename?: boolean): string;
|
|
40
|
+
export type SourceNavigation = {
|
|
41
|
+
selectedAnnotation: SourceAnnotation | undefined;
|
|
42
|
+
onSelectAnnotation: (annotation: SourceAnnotation) => void;
|
|
43
|
+
};
|
|
44
|
+
export {};
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
import { isCommitRev, shortRev } from "./changes.js";
|
|
2
|
+
export function parseCallStack(source) {
|
|
3
|
+
return source.split("\n").map((line) => {
|
|
4
|
+
const annotation = parseAnnotation(line);
|
|
5
|
+
return {
|
|
6
|
+
...annotation,
|
|
7
|
+
title: callStackRow(annotation.text).description.trim(),
|
|
8
|
+
};
|
|
9
|
+
});
|
|
10
|
+
}
|
|
11
|
+
/** A call stack row's change mark, tree prefix, and the call it describes. */
|
|
12
|
+
export function callStackRow(text) {
|
|
13
|
+
const sign = text.startsWith("+") ? "+" : text.startsWith("-") ? "-" : " ";
|
|
14
|
+
const label = text.replace(/^[+ -]/, "");
|
|
15
|
+
const tree = /^[ \t│┃├└─]*/u.exec(label)[0];
|
|
16
|
+
return { sign, tree, description: label.slice(tree.length) };
|
|
17
|
+
}
|
|
18
|
+
export function parseAnnotation(line) {
|
|
19
|
+
const references = [];
|
|
20
|
+
const text = line.replace(/\s*\[\[([^[\]\n]+)\]\]/g, (match, value) => {
|
|
21
|
+
const reference = parseReference(value);
|
|
22
|
+
if (reference === undefined)
|
|
23
|
+
return match;
|
|
24
|
+
references.push(reference);
|
|
25
|
+
return "";
|
|
26
|
+
});
|
|
27
|
+
return { text, references };
|
|
28
|
+
}
|
|
29
|
+
export function parseReference(value) {
|
|
30
|
+
const revMatch = /^([^:#[\]\n]+):(.+)$/.exec(value);
|
|
31
|
+
const rev = revMatch !== null && isCommitRev(revMatch[1]) ? revMatch[1] : undefined;
|
|
32
|
+
const target = rev === undefined ? value : revMatch[2];
|
|
33
|
+
const file = /^([^#:[\]\n]+)(?:#(.+))?$/.exec(target);
|
|
34
|
+
if (file === null || file[1].trim().length === 0)
|
|
35
|
+
return undefined;
|
|
36
|
+
const path = file[1].trim();
|
|
37
|
+
const fragment = file[2];
|
|
38
|
+
const base = rev === undefined
|
|
39
|
+
? { kind: "file", path }
|
|
40
|
+
: { kind: "file", rev, path };
|
|
41
|
+
if (fragment === undefined)
|
|
42
|
+
return base;
|
|
43
|
+
const range = /^L([1-9]\d*)(?:-L?([1-9]\d*))?$/.exec(fragment);
|
|
44
|
+
if (range !== null)
|
|
45
|
+
return {
|
|
46
|
+
...base,
|
|
47
|
+
start: Number(range[1]),
|
|
48
|
+
end: Number(range[2] === undefined ? range[1] : range[2]),
|
|
49
|
+
};
|
|
50
|
+
if (!/^[\w$]+(?:\.[\w$]+)*$/.test(fragment))
|
|
51
|
+
return undefined;
|
|
52
|
+
return { ...base, symbol: fragment };
|
|
53
|
+
}
|
|
54
|
+
/** Short label; pass `basename` for inline prose. */
|
|
55
|
+
export function referenceLabel(reference, basename = false) {
|
|
56
|
+
if (reference.kind === "changes")
|
|
57
|
+
return shortRev(reference.rev);
|
|
58
|
+
const path = basename ? reference.path.split("/").pop() : reference.path;
|
|
59
|
+
const rev = reference.rev === undefined ? "" : `${shortRev(reference.rev)}:`;
|
|
60
|
+
if (reference.symbol !== undefined)
|
|
61
|
+
return `${rev}${path}#${reference.symbol}`;
|
|
62
|
+
if (reference.start !== undefined)
|
|
63
|
+
return `${rev}${path}#L${reference.start}-L${reference.end}`;
|
|
64
|
+
return `${rev}${path}`;
|
|
65
|
+
}
|
package/lib/changes.d.ts
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A set of changes the diff panel can show: one commit (`a1b2c3d`), a commit
|
|
3
|
+
* range (`a1b2c3d..e4f5a6b`), uncommitted changes (`working`, `staged`,
|
|
4
|
+
* `unstaged`), a range that ends in them (`a1b2c3d..staged`,
|
|
5
|
+
* `a1b2c3d..working`), or `all` changes the range picker lists.
|
|
6
|
+
*/
|
|
7
|
+
export type Rev = string;
|
|
8
|
+
export declare const WORKING: Rev;
|
|
9
|
+
export declare const STAGED: Rev;
|
|
10
|
+
export declare const UNSTAGED: Rev;
|
|
11
|
+
export declare const ALL: Rev;
|
|
12
|
+
/** Revs a reference can name: commits and commit ranges. */
|
|
13
|
+
export declare function isCommitRev(value: string): boolean;
|
|
14
|
+
export declare function isRev(value: string): boolean;
|
|
15
|
+
export declare function shortRev(rev: Rev): string;
|
|
16
|
+
/** One row of the range picker, newest first: unstaged, staged, then commits. */
|
|
17
|
+
export type Delta = {
|
|
18
|
+
kind: "unstaged" | "staged";
|
|
19
|
+
additions: number;
|
|
20
|
+
deletions: number;
|
|
21
|
+
} | {
|
|
22
|
+
kind: "commit";
|
|
23
|
+
sha: string;
|
|
24
|
+
/** First parent, or the empty tree for a root commit. */
|
|
25
|
+
parent: string;
|
|
26
|
+
subject: string;
|
|
27
|
+
additions: number;
|
|
28
|
+
deletions: number;
|
|
29
|
+
};
|
|
30
|
+
export type DeltasResponse = {
|
|
31
|
+
deltas?: Delta[];
|
|
32
|
+
error?: string;
|
|
33
|
+
};
|
|
34
|
+
/** Picked rows, as indexes into the delta list: `newest <= oldest`. */
|
|
35
|
+
export type DeltaWindow = {
|
|
36
|
+
newest: number;
|
|
37
|
+
oldest: number;
|
|
38
|
+
};
|
|
39
|
+
/**
|
|
40
|
+
* The rev for picked rows. A window is always explicit, even when it covers
|
|
41
|
+
* every row: `all` is resolved against the default list, which may be shorter
|
|
42
|
+
* than one extended to reach an older rev.
|
|
43
|
+
*/
|
|
44
|
+
export declare function windowRev(deltas: Delta[], window: DeltaWindow): Rev;
|
|
45
|
+
/** The rows a rev covers, or undefined when the list cannot show it. */
|
|
46
|
+
export declare function revWindow(deltas: Delta[], rev: Rev): DeltaWindow | undefined;
|
|
47
|
+
/** "All commits", one commit's title, Unstaged or Staged, or `<oldest>…<newest>` for a range. */
|
|
48
|
+
export declare function windowLabel(deltas: Delta[], window: DeltaWindow): string;
|
|
49
|
+
export type ChangedFile = {
|
|
50
|
+
path: string;
|
|
51
|
+
/** Present when git detected a rename. */
|
|
52
|
+
prevPath?: string;
|
|
53
|
+
status: "added" | "deleted" | "modified" | "renamed";
|
|
54
|
+
additions: number;
|
|
55
|
+
deletions: number;
|
|
56
|
+
binary: boolean;
|
|
57
|
+
/**
|
|
58
|
+
* Full contents make every line reachable. Hosted GitHub viewers only get
|
|
59
|
+
* the hunk patch from the API.
|
|
60
|
+
*/
|
|
61
|
+
/** A missing side means the file did not exist there. */
|
|
62
|
+
contents?: {
|
|
63
|
+
old?: string;
|
|
64
|
+
new?: string;
|
|
65
|
+
};
|
|
66
|
+
patch?: string;
|
|
67
|
+
};
|
|
68
|
+
export type Changes = {
|
|
69
|
+
rev: Rev;
|
|
70
|
+
title: string;
|
|
71
|
+
/** Web page for these changes, such as a GitHub commit. */
|
|
72
|
+
url?: string;
|
|
73
|
+
/** GitHub listed only the first files; `url` has the rest. */
|
|
74
|
+
truncated?: boolean;
|
|
75
|
+
files: ChangedFile[];
|
|
76
|
+
};
|
|
77
|
+
/**
|
|
78
|
+
* Splits files into the ones to review, in `review` order, and the rest in
|
|
79
|
+
* their original order. Listing no files at all means every file is to be
|
|
80
|
+
* reviewed; listing only files to ignore means none is.
|
|
81
|
+
*/
|
|
82
|
+
export declare function orderForReview(files: ChangedFile[], review: string[], ignore?: string[]): {
|
|
83
|
+
reviewed: ChangedFile[];
|
|
84
|
+
other: ChangedFile[];
|
|
85
|
+
};
|
|
86
|
+
/** Gist file holding the changes a shared spec references, keyed by rev. */
|
|
87
|
+
export declare const GIST_CHANGES_FILE = "diffmap-changes.json";
|
|
88
|
+
/**
|
|
89
|
+
* Gist file holding the current contents of files a shared spec reads live,
|
|
90
|
+
* keyed by path: file excerpts and references without a commit.
|
|
91
|
+
*/
|
|
92
|
+
export declare const GIST_FILES_FILE = "diffmap-files.json";
|
|
93
|
+
export type ChangesResponse = {
|
|
94
|
+
changes?: Changes;
|
|
95
|
+
error?: string;
|
|
96
|
+
};
|
package/lib/changes.js
ADDED
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
export const WORKING = "working";
|
|
2
|
+
export const STAGED = "staged";
|
|
3
|
+
export const UNSTAGED = "unstaged";
|
|
4
|
+
export const ALL = "all";
|
|
5
|
+
const shaPattern = "[0-9a-f]{7,40}";
|
|
6
|
+
const commitRevPattern = new RegExp(`^${shaPattern}(?:\\.\\.${shaPattern})?$`);
|
|
7
|
+
const revPattern = new RegExp(`^(?:working|staged|unstaged|all|${shaPattern}(?:\\.\\.(?:${shaPattern}|staged|working))?)$`);
|
|
8
|
+
/** Revs a reference can name: commits and commit ranges. */
|
|
9
|
+
export function isCommitRev(value) {
|
|
10
|
+
return commitRevPattern.test(value);
|
|
11
|
+
}
|
|
12
|
+
export function isRev(value) {
|
|
13
|
+
return revPattern.test(value);
|
|
14
|
+
}
|
|
15
|
+
export function shortRev(rev) {
|
|
16
|
+
if (rev === WORKING)
|
|
17
|
+
return "Uncommitted";
|
|
18
|
+
if (rev === STAGED)
|
|
19
|
+
return "Staged";
|
|
20
|
+
if (rev === UNSTAGED)
|
|
21
|
+
return "Unstaged";
|
|
22
|
+
if (rev === ALL)
|
|
23
|
+
return "All commits";
|
|
24
|
+
return rev
|
|
25
|
+
.split("..")
|
|
26
|
+
.map((part) => part === STAGED || part === WORKING ? part : part.slice(0, 7))
|
|
27
|
+
.join("..");
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* The rev for picked rows. A window is always explicit, even when it covers
|
|
31
|
+
* every row: `all` is resolved against the default list, which may be shorter
|
|
32
|
+
* than one extended to reach an older rev.
|
|
33
|
+
*/
|
|
34
|
+
export function windowRev(deltas, window) {
|
|
35
|
+
const newest = deltas[window.newest];
|
|
36
|
+
const oldest = deltas[window.oldest];
|
|
37
|
+
if (window.newest === window.oldest)
|
|
38
|
+
return newest.kind === "commit" ? newest.sha : newest.kind;
|
|
39
|
+
// Only unstaged through staged: everything uncommitted.
|
|
40
|
+
if (oldest.kind !== "commit")
|
|
41
|
+
return WORKING;
|
|
42
|
+
const head = newest.kind === "commit"
|
|
43
|
+
? newest.sha
|
|
44
|
+
: newest.kind === "staged"
|
|
45
|
+
? STAGED
|
|
46
|
+
: WORKING;
|
|
47
|
+
return `${oldest.parent}..${head}`;
|
|
48
|
+
}
|
|
49
|
+
const same = (full, short) => full.startsWith(short);
|
|
50
|
+
/** The rows a rev covers, or undefined when the list cannot show it. */
|
|
51
|
+
export function revWindow(deltas, rev) {
|
|
52
|
+
if (rev === ALL)
|
|
53
|
+
return { newest: 0, oldest: deltas.length - 1 };
|
|
54
|
+
if (rev === UNSTAGED)
|
|
55
|
+
return { newest: 0, oldest: 0 };
|
|
56
|
+
if (rev === STAGED)
|
|
57
|
+
return { newest: 1, oldest: 1 };
|
|
58
|
+
if (rev === WORKING)
|
|
59
|
+
return { newest: 0, oldest: 1 };
|
|
60
|
+
const [first, second] = rev.split("..");
|
|
61
|
+
if (second === undefined) {
|
|
62
|
+
const index = deltas.findIndex((delta) => delta.kind === "commit" && same(delta.sha, first));
|
|
63
|
+
return index === -1 ? undefined : { newest: index, oldest: index };
|
|
64
|
+
}
|
|
65
|
+
const oldest = deltas.findIndex((delta) => delta.kind === "commit" && same(delta.parent, first));
|
|
66
|
+
const newest = second === WORKING
|
|
67
|
+
? 0
|
|
68
|
+
: second === STAGED
|
|
69
|
+
? 1
|
|
70
|
+
: deltas.findIndex((delta) => delta.kind === "commit" && same(delta.sha, second));
|
|
71
|
+
if (oldest === -1 || newest === -1 || newest > oldest)
|
|
72
|
+
return undefined;
|
|
73
|
+
return { newest, oldest };
|
|
74
|
+
}
|
|
75
|
+
function deltaName(delta) {
|
|
76
|
+
if (delta.kind === "commit")
|
|
77
|
+
return delta.sha.slice(0, 7);
|
|
78
|
+
return delta.kind === "staged" ? "Staged" : "Unstaged";
|
|
79
|
+
}
|
|
80
|
+
/** "All commits", one commit's title, Unstaged or Staged, or `<oldest>…<newest>` for a range. */
|
|
81
|
+
export function windowLabel(deltas, window) {
|
|
82
|
+
if (window.newest === 0 && window.oldest === deltas.length - 1)
|
|
83
|
+
return "All commits";
|
|
84
|
+
const newest = deltas[window.newest];
|
|
85
|
+
if (window.newest === window.oldest)
|
|
86
|
+
return newest.kind === "commit" ? newest.subject : deltaName(newest);
|
|
87
|
+
const oldest = deltas[window.oldest];
|
|
88
|
+
const from = oldest.kind === "commit" ? oldest.parent.slice(0, 7) : deltaName(oldest);
|
|
89
|
+
return `${from}…${deltaName(newest)}`;
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* Splits files into the ones to review, in `review` order, and the rest in
|
|
93
|
+
* their original order. Listing no files at all means every file is to be
|
|
94
|
+
* reviewed; listing only files to ignore means none is.
|
|
95
|
+
*/
|
|
96
|
+
export function orderForReview(files, review, ignore = []) {
|
|
97
|
+
if (review.length === 0 && ignore.length === 0)
|
|
98
|
+
return { reviewed: files, other: [] };
|
|
99
|
+
const reviewed = review.flatMap((path) => files.find((file) => file.path === path) ?? []);
|
|
100
|
+
return {
|
|
101
|
+
reviewed,
|
|
102
|
+
other: files.filter((file) => !reviewed.includes(file)),
|
|
103
|
+
};
|
|
104
|
+
}
|
|
105
|
+
/** Gist file holding the changes a shared spec references, keyed by rev. */
|
|
106
|
+
export const GIST_CHANGES_FILE = "diffmap-changes.json";
|
|
107
|
+
/**
|
|
108
|
+
* Gist file holding the current contents of files a shared spec reads live,
|
|
109
|
+
* keyed by path: file excerpts and references without a commit.
|
|
110
|
+
*/
|
|
111
|
+
export const GIST_FILES_FILE = "diffmap-files.json";
|
package/lib/cli.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|