@tanishqkancharla/diffmap 0.1.3 → 0.1.4

package/README.md

@@ -5,27 +5,26 @@
 diffmap is a set of personal skills as well as a web-viewer for Markdown files. It has a unique form of showing diffs using a mixture of callstack diffs and mermaid diagram links, which I've found to be personally extremely helpful in understanding massive diffs.
 
 ```sh
-npx diffmap path/to/file.md
+npx @tanishqkancharla/diffmap serve path/to/file.md
 ```
 
+Bare `npx @tanishqkancharla/diffmap path/to/file.md` is the same as `serve`.
+
 Share a secret gist and print a `diffmap.dev` link (requires [`gh`](https://cli.github.com/) logged in). Does not start a local server:
 
 ```sh
-npx diffmap share path/to.md
+npx @tanishqkancharla/diffmap share path/to.md
 ```
 
 Hosted viewer: `https://diffmap.dev/g/<gistId>` (optional `/<file.md>`; `#heading` is the table of contents). The page fetches the gist in the browser from `api.github.com`. Gists are unlisted, not private.
 
 ## Agent skills
 
-Install skills from this repository:
-
 ```sh
-npx skills add tanishqkancharla/diffmap --skill code-walkthrough
 npx skills add tanishqkancharla/diffmap --skill generate-spec
 ```
 
-`code-walkthrough` explains landed changes. `generate-spec` writes a phased spec for work that has not happened yet, then serves `specs/<name>.md` with diffmap.
+Keeps a spec in `specs/` that stays true to what's planned versus already in the tree. Serve it with diffmap. Share from a GitHub PR (`https://diffmap.dev/<owner>/<repo>/pull/<n>/specs/<name>.md`) or `npx @tanishqkancharla/diffmap share`.
 
 Options:
 
@@ -41,7 +40,7 @@ Vite connections do not keep it alive.
 List every running viewer, including viewers using custom ports:
 
 ```sh
-npx diffmap list
+npx @tanishqkancharla/diffmap list
 ```
 
 Request the page with `Accept: text/markdown` to read the current source file
@@ -54,10 +53,14 @@ curl -H 'Accept: text/markdown' http://127.0.0.1:4177/
 ## Library
 
 ```ts
-import { startServer, parseFence, parseViewerDocument } from "diffmap";
+import {
+  startServer,
+  parseFence,
+  parseViewerDocument,
+} from "@tanishqkancharla/diffmap";
 ```
 
-`parseViewerDocument` turns markdown into the page document with [md4x](https://github.com/unjs/md4x). `startServer` listens. The generate-spec and code-walkthrough skills own spec vs walkthrough section order; the viewer does not.
+`parseViewerDocument` turns markdown into the page document with [md4x](https://github.com/unjs/md4x). `startServer` listens. The generate-spec skill owns document shape; the viewer does not.
 
 ## Fences
 
@@ -176,7 +179,7 @@ Resolution uses the workspace's TypeScript configuration and current files.
 Deleted files and lines that no longer match the workspace show a message;
 their call stack references still highlight the embedded old-side diff.
 
-Run `npx diffmap fixtures/annotations.md` for an example
+Run `npx @tanishqkancharla/diffmap fixtures/annotations.md` for an example
 with old/new references, multiple files, and unchanged context.
 
 ## Link Mermaid nodes and edges

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanishqkancharla/diffmap",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Serve a spec or code walkthrough as a local page",
   "license": "MIT",
   "author": "Tanishq Kancharla",
@@ -33,7 +33,7 @@
     "lint:fix": "oxlint --fix src vite.config.ts vite.gist.config.ts bin.js",
     "prepublishOnly": "npm run typecheck && npm run lint && npm run format:check",
     "release": "npm publish",
-    "test": "tsx --test src/gist/route.test.ts",
+    "test": "tsx --test src/parseViewer.test.ts src/gist/route.test.ts src/github/route.test.ts src/github/patch.test.ts src/github/fetchRepo.test.ts src/viewer/sourceHeader.test.ts",
     "typecheck": "tsc --noEmit",
     "build": "vite build",
     "build:gist": "vite build",

package/src/cli.ts

@@ -6,65 +6,76 @@ import { listRunningDiffmaps } from "./registry.js";
 import { startServer } from "./serve.js";
 import { shareMarkdownFile } from "./share.js";
 
+const serveArgs = z.object({
+  file: z.string().describe("Path to the markdown file"),
+});
+
+const serveOptions = z.object({
+  port: z.coerce.number().optional().describe("Port (default 4177)"),
+  root: z.string().optional().describe("Workspace root for file excerpts"),
+});
+
+const serveOutput = z.object({
+  url: z.string(),
+  file: z.string(),
+});
+
+type ServeContext = {
+  args: { file: string };
+  options: { port?: number | undefined; root?: string | undefined };
+  error: (input: { code: string; message: string }) => never;
+};
+
+async function* runServe(c: ServeContext) {
+  const started = await startServer({
+    filePath: resolveFromInvokeCwd(c.args.file),
+    workspaceRoot:
+      c.options.root === undefined
+        ? resolveFromInvokeCwd(".")
+        : resolveFromInvokeCwd(c.options.root),
+    port: c.options.port === undefined ? 4177 : c.options.port,
+  });
+  if (started instanceof Error) {
+    return c.error({
+      code: "DIFFMAP",
+      message: started.message,
+    });
+  }
+  yield { url: started.url, file: started.filePath };
+  await started.closed;
+  return { url: started.url, file: started.filePath };
+}
+
 const cli = Cli.create("diffmap", {
-  description: "Serve a spec or code walkthrough as a local page",
+  description: "Serve a spec locally, or share it as a gist",
   version: "0.1.3",
-  args: z.object({
-    file: z.string().describe("Path to the markdown file"),
-  }),
-  options: z.object({
-    port: z.coerce.number().optional().describe("Port (default 4177)"),
-    root: z.string().optional().describe("Workspace root for file excerpts"),
-  }),
-  output: z.object({
-    url: z.string(),
-    file: z.string(),
-  }),
-  async *run(c) {
-    const started = await startServer({
-      filePath: resolveFromInvokeCwd(c.args.file),
-      workspaceRoot:
-        c.options.root === undefined
-          ? resolveFromInvokeCwd(".")
-          : resolveFromInvokeCwd(c.options.root),
-      port: c.options.port === undefined ? 4177 : c.options.port,
-    });
-    if (started instanceof Error) {
-      return c.error({
-        code: "DIFFMAP",
-        message: started.message,
-      });
-    }
-    yield { url: started.url, file: started.filePath };
-    await started.closed;
-    return { url: started.url, file: started.filePath };
-  },
-})
-  .command("list", {
-    description: "List running diffmap viewers",
-    output: z.object({
-      instances: z.array(
-        z.object({
-          pid: z.number(),
-          title: z.string(),
-          url: z.string(),
-          file: z.string(),
-        }),
-      ),
-    }),
-    async run(c) {
-      const instances = await listRunningDiffmaps();
-      if (instances instanceof Error) {
-        return c.error({
-          code: "DIFFMAP",
-          message: instances.message,
-        });
-      }
-      return c.ok({ instances });
+  args: serveArgs,
+  options: serveOptions,
+  output: serveOutput,
+  hint: "`serve <spec.md>` runs the local viewer. `share <spec.md>` publishes a secret gist.",
+  examples: [
+    {
+      args: { file: "spec.md" },
+      description: "Same as `diffmap serve spec.md`",
     },
+  ],
+  run: runServe,
+})
+  .command("serve", {
+    description: "Run the local viewer server",
+    args: serveArgs,
+    options: serveOptions,
+    output: serveOutput,
+    examples: [
+      {
+        args: { file: "spec.md" },
+        description: "Open the local viewer",
+      },
+    ],
+    run: runServe,
   })
   .command("share", {
-    description: "Upload a walkthrough gist and print the diffmap.dev URL",
+    description: "Publish a secret gist and print https://diffmap.dev/g/<id>",
     args: z.object({
       file: z.string().describe("Path to the markdown file"),
     }),
@@ -76,6 +87,12 @@ const cli = Cli.create("diffmap", {
       gistUrl: z.string(),
       viewerUrl: z.string(),
     }),
+    examples: [
+      {
+        args: { file: "spec.md" },
+        description: "Secret gist → https://diffmap.dev/g/<id>",
+      },
+    ],
     async run(c) {
       const shared = await shareMarkdownFile({
         filePath: resolveFromInvokeCwd(c.args.file),
@@ -89,6 +106,29 @@ const cli = Cli.create("diffmap", {
       }
       return c.ok(shared);
     },
+  })
+  .command("list", {
+    description: "List running diffmap viewers",
+    output: z.object({
+      instances: z.array(
+        z.object({
+          pid: z.number(),
+          title: z.string(),
+          url: z.string(),
+          file: z.string(),
+        }),
+      ),
+    }),
+    async run(c) {
+      const instances = await listRunningDiffmaps();
+      if (instances instanceof Error) {
+        return c.error({
+          code: "DIFFMAP",
+          message: instances.message,
+        });
+      }
+      return c.ok({ instances });
+    },
   });
 
 await cli.serve();

package/src/contentPlugin.ts

@@ -15,9 +15,11 @@ export function diffmapContentPlugin(input: {
     async load(id) {
       if (id !== virtualId) return;
       const source = await fs.readFile(input.filePath, "utf8");
-      const document = parseViewerDocument(source);
-      if (document instanceof Error) throw document;
-      return `export const viewerDocument = ${JSON.stringify(document)};`;
+      const document = parseViewerDocument(source, input.filePath);
+      if (document instanceof Error) {
+        return `export const viewerDocument = null; export const parseError = ${JSON.stringify(document.message)};`;
+      }
+      return `export const viewerDocument = ${JSON.stringify(document)}; export const parseError = null;`;
     },
     transformIndexHtml(html) {
       return html.replaceAll(

package/src/errors.ts

@@ -17,7 +17,7 @@ export class DiffmapRegistryError extends errore.createTaggedError({
 
 export class DiffmapMermaidError extends errore.createTaggedError({
   name: "DiffmapMermaidError",
-  message: "diffmap could not render mermaid",
+  message: "diffmap could not parse mermaid in $path ($where): $reason",
 }) {}
 
 export class DiffmapParseError extends errore.createTaggedError({

package/src/gist/GistApp.tsx

@@ -6,6 +6,7 @@ import { parseViewerDocument } from "../parseViewer.ts";
 import type { ViewerDocument } from "../parseViewer.ts";
 import { ViewerApp } from "../viewer/ViewerApp.tsx";
 import { loadGistMarkdown, type GistDocument } from "./fetchGist.ts";
+import { GistPinContext } from "./pin.ts";
 import { GistLanding, GistLoading, GistStatus } from "./GistStatus.tsx";
 import {
   gistPath,
@@ -151,24 +152,32 @@ export function GistApp() {
   }
 
   return (
-    <ViewerApp
-      key={`${view.gist.id}:${view.file}`}
-      document={view.document}
-      mode="gist"
-      headerActions={
-        <GistHeader
-          gistId={view.gist.id}
-          htmlUrl={view.gist.htmlUrl}
-          files={view.gist.files}
-          current={view.file}
-          onSelect={(file) => {
-            const next = gistPath(view.gist.id, file);
-            window.history.pushState({}, "", next);
-            setRoute(parseGistPath(next));
-          }}
-        />
-      }
-    />
+    <GistPinContext.Provider
+      value={{
+        gistId: view.gist.id,
+        file: view.file,
+        htmlUrl: view.gist.htmlUrl,
+      }}
+    >
+      <ViewerApp
+        key={`${view.gist.id}:${view.file}`}
+        document={view.document}
+        mode="gist"
+        headerActions={
+          <GistHeader
+            gistId={view.gist.id}
+            htmlUrl={view.gist.htmlUrl}
+            files={view.gist.files}
+            current={view.file}
+            onSelect={(file) => {
+              const next = gistPath(view.gist.id, file);
+              window.history.pushState({}, "", next);
+              setRoute(parseGistPath(next));
+            }}
+          />
+        }
+      />
+    </GistPinContext.Provider>
   );
 }
 
@@ -196,7 +205,10 @@ async function loadView(
       file: file ?? "",
     };
   }
-  const parsed = parseViewerDocument(loaded.gist.chosen.content);
+  const parsed = parseViewerDocument(
+    loaded.gist.chosen.content,
+    loaded.gist.chosen.name,
+  );
   if (parsed instanceof Error) {
     return {
       kind: "parse-error",

package/src/gist/GistStatus.tsx

@@ -19,6 +19,7 @@ export function GistStatus(props: {
   children: ReactNode;
   gistId?: string;
   gistUrl?: string;
+  linkLabel?: string;
 }) {
   const shell = useStyles(styles.shell);
   const header = useStyles(styles.header);
@@ -39,7 +40,9 @@ export function GistStatus(props: {
         {props.children}
         {gistUrl !== undefined && (
           <P>
-            <Link href={gistUrl}>Open gist on GitHub</Link>
+            <Link href={gistUrl}>
+              {props.linkLabel ?? "Open gist on GitHub"}
+            </Link>
           </P>
         )}
       </main>
@@ -47,10 +50,10 @@ export function GistStatus(props: {
   );
 }
 
-export function GistLoading() {
+export function GistLoading(props: { title?: string }) {
   const row = useStyles(styles.loading);
   return (
-    <GistStatus title="Loading gist…">
+    <GistStatus title={props.title ?? "Loading gist…"}>
       <div className={row}>
         <Thinking />
       </div>
@@ -64,21 +67,32 @@ export function GistLanding() {
     <GistStatus title="diffmap">
       <P>
         A hosted viewer for diffmap walkthroughs. This page fetches a GitHub
-        gist in your browser. There is no server holding the markdown.
+        gist or a public repo file in your browser. There is no server holding
+        the markdown.
       </P>
       <P>
-        Canonical URL:{" "}
+        Canonical gist URL:{" "}
         <code className={code}>https://diffmap.dev/g/&lt;gistId&gt;</code>.
         Optional file:{" "}
-        <code className={code}>/g/&lt;gistId&gt;/&lt;file.md&gt;</code>. Heading
-        hashes stay in the fragment, same as the local viewer.
+        <code className={code}>/g/&lt;gistId&gt;/&lt;file.md&gt;</code>. GitHub
+        spec:{" "}
+        <code className={code}>
+          https://diffmap.dev/&lt;owner&gt;/&lt;repo&gt;/pull/&lt;n&gt;/&lt;path.md&gt;
+        </code>{" "}
+        or{" "}
+        <code className={code}>
+          /&lt;owner&gt;/&lt;repo&gt;/commit/&lt;sha&gt;/&lt;path.md&gt;
+        </code>
+        . Heading hashes stay in the fragment, same as the local viewer.
       </P>
       <P>
         Share a secret gist (requires <code className={code}>gh</code>
         ):
       </P>
       <P>
-        <code className={code}>npx diffmap share path/to.md</code>
+        <code className={code}>
+          npx @tanishqkancharla/diffmap share path/to.md
+        </code>
       </P>
       <P>
         Secret gists are unlisted, not private. Anyone with the id can read

package/src/gist/main.tsx

@@ -2,7 +2,7 @@ import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import { MauiProvider } from "maui";
 import { rewritePiGistUrl } from "./route.ts";
-import { GistApp } from "./GistApp.tsx";
+import { HostApp } from "../host/HostApp.tsx";
 import "../viewer/styles.css";
 
 const rewritten = rewritePiGistUrl(
@@ -19,7 +19,7 @@ if (root === null) throw new Error("diffmap root element is missing");
 createRoot(root).render(
   <StrictMode>
     <MauiProvider>
-      <GistApp />
+      <HostApp />
     </MauiProvider>
   </StrictMode>,
 );

package/src/gist/pin.ts

@@ -0,0 +1,14 @@
+import { createContext, useContext } from "react";
+
+/** Gist snapshot: identify the gist file, never a fake owner/repo. */
+export type GistPin = {
+  gistId: string;
+  file: string;
+  htmlUrl: string;
+};
+
+export const GistPinContext = createContext<GistPin | undefined>(undefined);
+
+export function useGistPin() {
+  return useContext(GistPinContext);
+}