@ascribed/astro 0.2.1-next.9 → 0.3.0

package/dist/records.d.ts

@@ -0,0 +1,136 @@
+/** How a page is treated: listed, listed and not to be quoted, or not listed. */
+export type Listing = "listed" | "unquoted" | "unlisted";
+/**
+ * Where a page's listing comes from: `default` when nothing sets it, `page`
+ * for the page's own, and for a rule of `[listing]` its level (`site`,
+ * `folder`, or `type`), its folder or type, the rule as written, and its line
+ * in `ascribe.toml`.
+ */
+export interface ListingFrom {
+    level: "default" | "page" | "site" | "folder" | "type";
+    folder?: string;
+    type?: string;
+    rule?: string;
+    line?: number;
+}
+/** One page's record, with the route it's keyed by. */
+export interface PageRecord {
+    /** The page's route, from the host's root. */
+    route: string;
+    /** The page's path from the content root, with `/`. */
+    source: string;
+    /** The page's title, as plain text. */
+    title?: string;
+    /** The page's description, as plain text on one line. */
+    description?: string;
+    /** The page's own address, absolute, when the project sets `[consumer] site`. */
+    canonical?: string;
+    listing: Listing;
+    /** Where `listing` comes from: the page, a rule of `[listing]`, or neither. */
+    listing_from: ListingFrom;
+    /** The address of the page's Markdown version, from the host's root, when the build publishes one. */
+    markdown?: string;
+    /**
+     * The page's place in the site, from the top down to the page itself: the
+     * page at each of its route's folders that has one, then the page. Absent
+     * in records an earlier Ascribe wrote.
+     */
+    breadcrumbs?: Step[];
+}
+/** One step of a page's breadcrumbs: a page's route, from the host's root, and its title. */
+export interface Step {
+    route: string;
+    title: string;
+}
+/** What a kind of crawler is for: gathering training data, building an AI search index, or fetching at a person's request. */
+type Purpose = "training" | "search" | "on-request";
+/** The group of `robots.txt` a disallowed purpose writes. */
+export interface RobotsGroup {
+    purpose: Purpose;
+    /** Every token of the purpose the binary knows, each a `User-agent` line. */
+    user_agents: string[];
+    /** The group's rules: `Disallow: /`. */
+    lines: string[];
+}
+/** What a project says to crawlers. */
+export interface Robots {
+    /** The project's own lines, with paths from the host's root. */
+    lines: string[];
+    /** What the project says of each purpose it sets. */
+    purposes?: Partial<Record<Purpose, "allow" | "disallow">>;
+    /** A group for each purpose the project disallows. */
+    groups?: RobotsGroup[];
+}
+/** `_ascribe/pages.json`. */
+export interface PageRecords {
+    version: number;
+    site?: string;
+    pages: Record<string, Omit<PageRecord, "route">>;
+    robots: Robots;
+}
+/** What one project says to crawlers, by the name of its first entry. */
+export interface ProjectRobots {
+    name: string;
+    robots: Robots;
+}
+/** The records in a build's site output, or `undefined` when there aren't any. */
+export declare function readRecords(siteRoot: string): PageRecords | undefined;
+/**
+ * The record of the page whose source path is `source`, in the build whose
+ * site output is at `siteRoot`, or `undefined` when it has none. Read again
+ * when the file changes, as it does with each build in `astro dev`.
+ */
+export declare function recordFor(siteRoot: string, source: string): PageRecord | undefined;
+/** The records' pages, each with its route, in the file's order. */
+export declare function pageList(records: PageRecords | undefined): PageRecord[];
+/**
+ * A route as the sitemap compares it: with a leading `/` and no trailing one,
+ * except at the root, so `/docs/` and `/docs` are one page.
+ */
+export declare function routeKey(route: string): string;
+/** A route ending the way Astro's `trailingSlash` says, as a built page's address. */
+export declare function routeAs(route: string, trailingSlash: "always" | "never" | "ignore"): string;
+/** What the sitemap is drawn from. */
+export interface SitemapSources {
+    /** Every project's records. */
+    projects: readonly PageRecord[][];
+    /**
+     * Whether a project's page has a route in the site: was built, or, in
+     * `astro dev`, matches one of the site's routes.
+     */
+    routed: (route: string) => boolean;
+    /** The site's own pages, each by its route from the host's root. */
+    sitePages: readonly string[];
+    /** Routes from the host's root to leave out: forwarding pages, the not-found page, and the site's list. */
+    excluded: readonly string[];
+    /** Astro's `site`. */
+    site: string;
+}
+/**
+ * The sitemap's addresses, absolute, sorted, each once: every listed page of
+ * every project that has a route in the site, and every page of the site's
+ * own, less the excluded routes. A project's page that isn't listed is left
+ * out, and so is a page of the site's own at the same route as one.
+ */
+export declare function sitemapAddresses(sources: SitemapSources): string[];
+/** A sitemap of `addresses`, with no dates. */
+export declare function sitemapXml(addresses: readonly string[]): string;
+/**
+ * A site's `robots.txt` from what each project says to crawlers: a group for
+ * each purpose a project disallows, once for the site, then a
+ * `User-agent: *` group with every project's lines before its first
+ * `User-agent` line, which are for every crawler, then the groups each
+ * project wrote whole, then the sitemap's address. `undefined` when it would
+ * say nothing.
+ */
+export declare function robotsText(projects: readonly Robots[], sitemap: string | undefined): string | undefined;
+/**
+ * Two projects that say contradictory things about one purpose, as
+ * sentences: one allows it and the other disallows it. A site has one
+ * `robots.txt`, so they must agree. A project that says nothing of a purpose
+ * agrees with either.
+ */
+export declare function purposeConflicts(projects: readonly ProjectRobots[]): string[];
+/** Where the sitemap is, from the host's root: at Astro's `base`. */
+export declare function sitemapRoute(base: string): string;
+export {};

package/dist/records.js

@@ -0,0 +1,182 @@
+// The page records: `_ascribe/pages.json` in a build's site output
+// (output-layout contract §1.3), what each page tells every reader that isn't
+// a person. The integration writes from them a page's head (`Head.astro`),
+// the site's one sitemap, and its one `robots.txt`, from every project's
+// records together, at the host's root.
+import { readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { normalizeBase } from "./project.js";
+/** The records' format version this reads. */
+const VERSION = 1;
+function recordsFile(siteRoot) {
+    return path.join(siteRoot, "_ascribe", "pages.json");
+}
+/** The records in a build's site output, or `undefined` when there aren't any. */
+export function readRecords(siteRoot) {
+    const file = recordsFile(siteRoot);
+    let text;
+    try {
+        text = readFileSync(file, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const records = JSON.parse(text);
+    if (records.version !== VERSION) {
+        throw new Error(`@ascribed/astro: ${file} is version ${String(records.version)} of the page records, and this version of the integration reads version ${VERSION}. Update @ascribed/astro and @ascribed/cli together.`);
+    }
+    return records;
+}
+/** A build's records by source path, as last read, and when its file was written. */
+const bySource = new Map();
+/**
+ * The record of the page whose source path is `source`, in the build whose
+ * site output is at `siteRoot`, or `undefined` when it has none. Read again
+ * when the file changes, as it does with each build in `astro dev`.
+ */
+export function recordFor(siteRoot, source) {
+    let written;
+    try {
+        written = statSync(recordsFile(siteRoot)).mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+    let known = bySource.get(siteRoot);
+    if (known === undefined || known.written !== written) {
+        const pages = new Map();
+        for (const record of pageList(readRecords(siteRoot))) {
+            if (!pages.has(record.source))
+                pages.set(record.source, record);
+        }
+        known = { written, pages };
+        bySource.set(siteRoot, known);
+    }
+    return known.pages.get(source);
+}
+/** The records' pages, each with its route, in the file's order. */
+export function pageList(records) {
+    return Object.entries(records?.pages ?? {}).map(([route, page]) => ({ route, ...page }));
+}
+/**
+ * A route as the sitemap compares it: with a leading `/` and no trailing one,
+ * except at the root, so `/docs/` and `/docs` are one page.
+ */
+export function routeKey(route) {
+    const withSlash = route.startsWith("/") ? route : `/${route}`;
+    return withSlash.length > 1 && withSlash.endsWith("/") ? withSlash.slice(0, -1) : withSlash;
+}
+/** A route ending the way Astro's `trailingSlash` says, as a built page's address. */
+export function routeAs(route, trailingSlash) {
+    if (trailingSlash === "never")
+        return routeKey(route);
+    if (trailingSlash === "always" && !route.endsWith("/"))
+        return `${route}/`;
+    return route;
+}
+/**
+ * The sitemap's addresses, absolute, sorted, each once: every listed page of
+ * every project that has a route in the site, and every page of the site's
+ * own, less the excluded routes. A project's page that isn't listed is left
+ * out, and so is a page of the site's own at the same route as one.
+ */
+export function sitemapAddresses(sources) {
+    const excluded = new Set(sources.excluded.map(routeKey));
+    const records = new Set();
+    const routes = new Map();
+    for (const pages of sources.projects) {
+        for (const page of pages) {
+            const key = routeKey(page.route);
+            records.add(key);
+            if (page.listing === "unlisted" || excluded.has(key) || !sources.routed(page.route))
+                continue;
+            if (!routes.has(key))
+                routes.set(key, page.route);
+        }
+    }
+    for (const route of sources.sitePages) {
+        const key = routeKey(route);
+        if (records.has(key) || excluded.has(key) || routes.has(key))
+            continue;
+        routes.set(key, route);
+    }
+    return [
+        ...new Set([...routes.values()].map((route) => new URL(route, sources.site).href)),
+    ].sort();
+}
+function escapeXml(text) {
+    return text
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&apos;");
+}
+/** A sitemap of `addresses`, with no dates. */
+export function sitemapXml(addresses) {
+    const urls = addresses.map((address) => `  <url><loc>${escapeXml(address)}</loc></url>\n`);
+    return ('<?xml version="1.0" encoding="UTF-8"?>\n' +
+        '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n' +
+        urls.join("") +
+        "</urlset>\n");
+}
+const USER_AGENT = /^\s*user-agent\s*:/i;
+/**
+ * A site's `robots.txt` from what each project says to crawlers: a group for
+ * each purpose a project disallows, once for the site, then a
+ * `User-agent: *` group with every project's lines before its first
+ * `User-agent` line, which are for every crawler, then the groups each
+ * project wrote whole, then the sitemap's address. `undefined` when it would
+ * say nothing.
+ */
+export function robotsText(projects, sitemap) {
+    const purposes = new Map();
+    const everyone = [];
+    const groups = [];
+    for (const robots of projects) {
+        for (const group of robots.groups ?? []) {
+            if (purposes.has(group.purpose))
+                continue;
+            purposes.set(group.purpose, [
+                ...group.user_agents.map((agent) => `User-agent: ${agent}`),
+                ...group.lines,
+            ]);
+        }
+        const lines = robots.lines;
+        const first = lines.findIndex((line) => USER_AGENT.test(line));
+        everyone.push(...(first === -1 ? lines : lines.slice(0, first)));
+        if (first !== -1)
+            groups.push(lines.slice(first));
+    }
+    const blocks = [...purposes.values()];
+    if (everyone.length > 0)
+        blocks.push(["User-agent: *", ...everyone]);
+    blocks.push(...groups);
+    if (sitemap !== undefined)
+        blocks.push([`Sitemap: ${sitemap}`]);
+    if (blocks.length === 0)
+        return undefined;
+    return `${blocks.map((block) => block.join("\n")).join("\n\n")}\n`;
+}
+/**
+ * Two projects that say contradictory things about one purpose, as
+ * sentences: one allows it and the other disallows it. A site has one
+ * `robots.txt`, so they must agree. A project that says nothing of a purpose
+ * agrees with either.
+ */
+export function purposeConflicts(projects) {
+    const problems = [];
+    for (const purpose of ["training", "search", "on-request"]) {
+        const allow = projects.find((p) => p.robots.purposes?.[purpose] === "allow");
+        const disallow = projects.find((p) => p.robots.purposes?.[purpose] === "disallow");
+        if (allow === undefined || disallow === undefined)
+            continue;
+        problems.push(`"${disallow.name}" has [crawlers] ${purpose} = "disallow" and "${allow.name}" has ${purpose} = "allow". The site has one robots.txt, so its projects must agree: make them the same, or remove one.`);
+    }
+    return problems;
+}
+/** Where the sitemap is, from the host's root: at Astro's `base`. */
+export function sitemapRoute(base) {
+    return `${normalizeBase(base)}sitemap.xml`;
+}
+//# sourceMappingURL=records.js.map

package/dist/records.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.js","sourceRoot":"","sources":["../src/records.ts"],"names":[],"mappings":"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","sourcesContent":["// The page records: `_ascribe/pages.json` in a build's site output\n// (output-layout contract §1.3), what each page tells every reader that isn't\n// a person. The integration writes from them a page's head (`Head.astro`),\n// the site's one sitemap, and its one `robots.txt`, from every project's\n// records together, at the host's root.\nimport { readFileSync, statSync } from \"node:fs\";\nimport path from \"node:path\";\nimport { normalizeBase } from \"./project.js\";\n\n/** The records' format version this reads. */\nconst VERSION = 1;\n\n/** How a page is treated: listed, listed and not to be quoted, or not listed. */\nexport type Listing = \"listed\" | \"unquoted\" | \"unlisted\";\n\n/**\n * Where a page's listing comes from: `default` when nothing sets it, `page`\n * for the page's own, and for a rule of `[listing]` its level (`site`,\n * `folder`, or `type`), its folder or type, the rule as written, and its line\n * in `ascribe.toml`.\n */\nexport interface ListingFrom {\n  level: \"default\" | \"page\" | \"site\" | \"folder\" | \"type\";\n  folder?: string;\n  type?: string;\n  rule?: string;\n  line?: number;\n}\n\n/** One page's record, with the route it's keyed by. */\nexport interface PageRecord {\n  /** The page's route, from the host's root. */\n  route: string;\n  /** The page's path from the content root, with `/`. */\n  source: string;\n  /** The page's title, as plain text. */\n  title?: string;\n  /** The page's description, as plain text on one line. */\n  description?: string;\n  /** The page's own address, absolute, when the project sets `[consumer] site`. */\n  canonical?: string;\n  listing: Listing;\n  /** Where `listing` comes from: the page, a rule of `[listing]`, or neither. */\n  listing_from: ListingFrom;\n  /** The address of the page's Markdown version, from the host's root, when the build publishes one. */\n  markdown?: string;\n  /**\n   * The page's place in the site, from the top down to the page itself: the\n   * page at each of its route's folders that has one, then the page. Absent\n   * in records an earlier Ascribe wrote.\n   */\n  breadcrumbs?: Step[];\n}\n\n/** One step of a page's breadcrumbs: a page's route, from the host's root, and its title. */\nexport interface Step {\n  route: string;\n  title: string;\n}\n\n/** What a kind of crawler is for: gathering training data, building an AI search index, or fetching at a person's request. */\ntype Purpose = \"training\" | \"search\" | \"on-request\";\n\n/** The group of `robots.txt` a disallowed purpose writes. */\nexport interface RobotsGroup {\n  purpose: Purpose;\n  /** Every token of the purpose the binary knows, each a `User-agent` line. */\n  user_agents: string[];\n  /** The group's rules: `Disallow: /`. */\n  lines: string[];\n}\n\n/** What a project says to crawlers. */\nexport interface Robots {\n  /** The project's own lines, with paths from the host's root. */\n  lines: string[];\n  /** What the project says of each purpose it sets. */\n  purposes?: Partial<Record<Purpose, \"allow\" | \"disallow\">>;\n  /** A group for each purpose the project disallows. */\n  groups?: RobotsGroup[];\n}\n\n/** `_ascribe/pages.json`. */\nexport interface PageRecords {\n  version: number;\n  site?: string;\n  pages: Record<string, Omit<PageRecord, \"route\">>;\n  robots: Robots;\n}\n\n/** What one project says to crawlers, by the name of its first entry. */\nexport interface ProjectRobots {\n  name: string;\n  robots: Robots;\n}\n\nfunction recordsFile(siteRoot: string): string {\n  return path.join(siteRoot, \"_ascribe\", \"pages.json\");\n}\n\n/** The records in a build's site output, or `undefined` when there aren't any. */\nexport function readRecords(siteRoot: string): PageRecords | undefined {\n  const file = recordsFile(siteRoot);\n  let text: string;\n  try {\n    text = readFileSync(file, \"utf8\");\n  } catch {\n    return undefined;\n  }\n  const records = JSON.parse(text) as PageRecords;\n  if (records.version !== VERSION) {\n    throw new Error(\n      `@ascribed/astro: ${file} is version ${String(records.version)} of the page records, and this version of the integration reads version ${VERSION}. Update @ascribed/astro and @ascribed/cli together.`,\n    );\n  }\n  return records;\n}\n\n/** A build's records by source path, as last read, and when its file was written. */\nconst bySource = new Map<string, { written: number; pages: Map<string, PageRecord> }>();\n\n/**\n * The record of the page whose source path is `source`, in the build whose\n * site output is at `siteRoot`, or `undefined` when it has none. Read again\n * when the file changes, as it does with each build in `astro dev`.\n */\nexport function recordFor(siteRoot: string, source: string): PageRecord | undefined {\n  let written: number;\n  try {\n    written = statSync(recordsFile(siteRoot)).mtimeMs;\n  } catch {\n    return undefined;\n  }\n  let known = bySource.get(siteRoot);\n  if (known === undefined || known.written !== written) {\n    const pages = new Map<string, PageRecord>();\n    for (const record of pageList(readRecords(siteRoot))) {\n      if (!pages.has(record.source)) pages.set(record.source, record);\n    }\n    known = { written, pages };\n    bySource.set(siteRoot, known);\n  }\n  return known.pages.get(source);\n}\n\n/** The records' pages, each with its route, in the file's order. */\nexport function pageList(records: PageRecords | undefined): PageRecord[] {\n  return Object.entries(records?.pages ?? {}).map(([route, page]) => ({ route, ...page }));\n}\n\n/**\n * A route as the sitemap compares it: with a leading `/` and no trailing one,\n * except at the root, so `/docs/` and `/docs` are one page.\n */\nexport function routeKey(route: string): string {\n  const withSlash = route.startsWith(\"/\") ? route : `/${route}`;\n  return withSlash.length > 1 && withSlash.endsWith(\"/\") ? withSlash.slice(0, -1) : withSlash;\n}\n\n/** A route ending the way Astro's `trailingSlash` says, as a built page's address. */\nexport function routeAs(route: string, trailingSlash: \"always\" | \"never\" | \"ignore\"): string {\n  if (trailingSlash === \"never\") return routeKey(route);\n  if (trailingSlash === \"always\" && !route.endsWith(\"/\")) return `${route}/`;\n  return route;\n}\n\n/** What the sitemap is drawn from. */\nexport interface SitemapSources {\n  /** Every project's records. */\n  projects: readonly PageRecord[][];\n  /**\n   * Whether a project's page has a route in the site: was built, or, in\n   * `astro dev`, matches one of the site's routes.\n   */\n  routed: (route: string) => boolean;\n  /** The site's own pages, each by its route from the host's root. */\n  sitePages: readonly string[];\n  /** Routes from the host's root to leave out: forwarding pages, the not-found page, and the site's list. */\n  excluded: readonly string[];\n  /** Astro's `site`. */\n  site: string;\n}\n\n/**\n * The sitemap's addresses, absolute, sorted, each once: every listed page of\n * every project that has a route in the site, and every page of the site's\n * own, less the excluded routes. A project's page that isn't listed is left\n * out, and so is a page of the site's own at the same route as one.\n */\nexport function sitemapAddresses(sources: SitemapSources): string[] {\n  const excluded = new Set(sources.excluded.map(routeKey));\n  const records = new Set<string>();\n  const routes = new Map<string, string>();\n  for (const pages of sources.projects) {\n    for (const page of pages) {\n      const key = routeKey(page.route);\n      records.add(key);\n      if (page.listing === \"unlisted\" || excluded.has(key) || !sources.routed(page.route)) continue;\n      if (!routes.has(key)) routes.set(key, page.route);\n    }\n  }\n  for (const route of sources.sitePages) {\n    const key = routeKey(route);\n    if (records.has(key) || excluded.has(key) || routes.has(key)) continue;\n    routes.set(key, route);\n  }\n  return [\n    ...new Set([...routes.values()].map((route) => new URL(route, sources.site).href)),\n  ].sort();\n}\n\nfunction escapeXml(text: string): string {\n  return text\n    .replaceAll(\"&\", \"&amp;\")\n    .replaceAll(\"<\", \"&lt;\")\n    .replaceAll(\">\", \"&gt;\")\n    .replaceAll('\"', \"&quot;\")\n    .replaceAll(\"'\", \"&apos;\");\n}\n\n/** A sitemap of `addresses`, with no dates. */\nexport function sitemapXml(addresses: readonly string[]): string {\n  const urls = addresses.map((address) => `  <url><loc>${escapeXml(address)}</loc></url>\\n`);\n  return (\n    '<?xml version=\"1.0\" encoding=\"UTF-8\"?>\\n' +\n    '<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">\\n' +\n    urls.join(\"\") +\n    \"</urlset>\\n\"\n  );\n}\n\nconst USER_AGENT = /^\\s*user-agent\\s*:/i;\n\n/**\n * A site's `robots.txt` from what each project says to crawlers: a group for\n * each purpose a project disallows, once for the site, then a\n * `User-agent: *` group with every project's lines before its first\n * `User-agent` line, which are for every crawler, then the groups each\n * project wrote whole, then the sitemap's address. `undefined` when it would\n * say nothing.\n */\nexport function robotsText(\n  projects: readonly Robots[],\n  sitemap: string | undefined,\n): string | undefined {\n  const purposes = new Map<Purpose, string[]>();\n  const everyone: string[] = [];\n  const groups: string[][] = [];\n  for (const robots of projects) {\n    for (const group of robots.groups ?? []) {\n      if (purposes.has(group.purpose)) continue;\n      purposes.set(group.purpose, [\n        ...group.user_agents.map((agent) => `User-agent: ${agent}`),\n        ...group.lines,\n      ]);\n    }\n    const lines = robots.lines;\n    const first = lines.findIndex((line) => USER_AGENT.test(line));\n    everyone.push(...(first === -1 ? lines : lines.slice(0, first)));\n    if (first !== -1) groups.push(lines.slice(first));\n  }\n  const blocks: string[][] = [...purposes.values()];\n  if (everyone.length > 0) blocks.push([\"User-agent: *\", ...everyone]);\n  blocks.push(...groups);\n  if (sitemap !== undefined) blocks.push([`Sitemap: ${sitemap}`]);\n  if (blocks.length === 0) return undefined;\n  return `${blocks.map((block) => block.join(\"\\n\")).join(\"\\n\\n\")}\\n`;\n}\n\n/**\n * Two projects that say contradictory things about one purpose, as\n * sentences: one allows it and the other disallows it. A site has one\n * `robots.txt`, so they must agree. A project that says nothing of a purpose\n * agrees with either.\n */\nexport function purposeConflicts(projects: readonly ProjectRobots[]): string[] {\n  const problems: string[] = [];\n  for (const purpose of [\"training\", \"search\", \"on-request\"] as const) {\n    const allow = projects.find((p) => p.robots.purposes?.[purpose] === \"allow\");\n    const disallow = projects.find((p) => p.robots.purposes?.[purpose] === \"disallow\");\n    if (allow === undefined || disallow === undefined) continue;\n    problems.push(\n      `\"${disallow.name}\" has [crawlers] ${purpose} = \"disallow\" and \"${allow.name}\" has ${purpose} = \"allow\". The site has one robots.txt, so its projects must agree: make them the same, or remove one.`,\n    );\n  }\n  return problems;\n}\n\n/** Where the sitemap is, from the host's root: at Astro's `base`. */\nexport function sitemapRoute(base: string): string {\n  return `${normalizeBase(base)}sitemap.xml`;\n}\n"]}

package/dist/review/devfile.d.ts

@@ -15,7 +15,12 @@ export declare function siteUrl(address: AddressInfo, options: {
     https: boolean;
     base: string;
 }): string;
-/** Writes `dev.json`. A failure is the caller's to log: it only costs the editor its link. */
+/**
+ * Writes `dev.json`. A failure is the caller's to log: it only costs the editor its link.
+ * `.ascribe` or `dev.json` that's a link (a symbolic link, or a junction on Windows, which
+ * Node's `lstat` reports as one) is refused, not written through: a committed link could
+ * lead anywhere.
+ */
 export declare function writeDevFile(projectDir: string, file: DevFile): void;
 /** Removes `dev.json` if this process wrote it. */
 export declare function removeDevFile(projectDir: string, pid: number): void;

package/dist/review/devfile.js

@@ -1,7 +1,7 @@
 // `.ascribe/dev.json`: where the dev server is, for the editor's Open Site
 // Preview. Written when the server starts, removed when it stops. A server
 // that crashed leaves it behind, so a reader checks the URL answers first.
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 /** `<project>/.ascribe/dev.json`. */
 export function devFilePath(projectDir) {
@@ -17,9 +17,19 @@ export function siteUrl(address, options) {
     const base = options.base.endsWith("/") ? options.base : `${options.base}/`;
     return `${options.https ? "https" : "http"}://${host}:${address.port}${base.startsWith("/") ? base : `/${base}`}`;
 }
-/** Writes `dev.json`. A failure is the caller's to log: it only costs the editor its link. */
+/**
+ * Writes `dev.json`. A failure is the caller's to log: it only costs the editor its link.
+ * `.ascribe` or `dev.json` that's a link (a symbolic link, or a junction on Windows, which
+ * Node's `lstat` reports as one) is refused, not written through: a committed link could
+ * lead anywhere.
+ */
 export function writeDevFile(projectDir, file) {
     const target = devFilePath(projectDir);
+    for (const at of [path.dirname(target), target]) {
+        if (lstatSync(at, { throwIfNoEntry: false })?.isSymbolicLink()) {
+            throw new Error(`${at} is a link; replace it with a folder or a file, or remove it`);
+        }
+    }
     mkdirSync(path.dirname(target), { recursive: true });
     writeFileSync(target, `${JSON.stringify(file, null, 2)}\n`);
 }

package/dist/review/devfile.js.map

@@ -1 +1 @@
-{"version":3,"file":"devfile.js","sourceRoot":"","sources":["../../src/review/devfile.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,2EAA2E;AAC3E,2EAA2E;AAC3E,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEzE,OAAO,IAAI,MAAM,WAAW,CAAC;AAY7B,qCAAqC;AACrC,MAAM,UAAU,WAAW,CAAC,UAAkB;IAC5C,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;AACvD,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,OAAO,CAAC,OAAoB,EAAE,OAAyC;IACrF,IAAI,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC;IAC3B,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,IAAI,GAAG,WAAW,CAAC;SAC5E,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,IAAI,GAAG,IAAI,IAAI,GAAG,CAAC;IAChD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,GAAG,CAAC;IAC5E,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,MAAM,IAAI,IAAI,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;AACpH,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,YAAY,CAAC,UAAkB,EAAE,IAAa;IAC5D,MAAM,MAAM,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;IACvC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACrD,aAAa,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;AAC9D,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,aAAa,CAAC,UAAkB,EAAE,GAAW;IAC3D,MAAM,MAAM,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;IACvC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAqB,CAAC;QAC7E,IAAI,OAAO,CAAC,GAAG,KAAK,GAAG;YAAE,OAAO;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IACD,MAAM,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAClC,CAAC","sourcesContent":["// `.ascribe/dev.json`: where the dev server is, for the editor's Open Site\n// Preview. Written when the server starts, removed when it stops. A server\n// that crashed leaves it behind, so a reader checks the URL answers first.\nimport { mkdirSync, readFileSync, rmSync, writeFileSync } from \"node:fs\";\nimport type { AddressInfo } from \"node:net\";\nimport path from \"node:path\";\n\n/** What `dev.json` holds. */\nexport interface DevFile {\n  /** The site's address: origin and base path, `http://localhost:4321/docs/`. */\n  url: string;\n  /** The build the dev server shows. */\n  build: string;\n  /** The dev server's process, so another server's file isn't removed. */\n  pid: number;\n}\n\n/** `<project>/.ascribe/dev.json`. */\nexport function devFilePath(projectDir: string): string {\n  return path.join(projectDir, \".ascribe\", \"dev.json\");\n}\n\n/** The site's address from the server's: a wildcard or loopback host is `localhost`. */\nexport function siteUrl(address: AddressInfo, options: { https: boolean; base: string }): string {\n  let host = address.address;\n  if ([\"::\", \"0.0.0.0\", \"::1\", \"\", \"localhost\"].includes(host)) host = \"localhost\";\n  else if (host.includes(\":\")) host = `[${host}]`;\n  const base = options.base.endsWith(\"/\") ? options.base : `${options.base}/`;\n  return `${options.https ? \"https\" : \"http\"}://${host}:${address.port}${base.startsWith(\"/\") ? base : `/${base}`}`;\n}\n\n/** Writes `dev.json`. A failure is the caller's to log: it only costs the editor its link. */\nexport function writeDevFile(projectDir: string, file: DevFile): void {\n  const target = devFilePath(projectDir);\n  mkdirSync(path.dirname(target), { recursive: true });\n  writeFileSync(target, `${JSON.stringify(file, null, 2)}\\n`);\n}\n\n/** Removes `dev.json` if this process wrote it. */\nexport function removeDevFile(projectDir: string, pid: number): void {\n  const target = devFilePath(projectDir);\n  try {\n    const current = JSON.parse(readFileSync(target, \"utf8\")) as Partial<DevFile>;\n    if (current.pid !== pid) return;\n  } catch {\n    return;\n  }\n  rmSync(target, { force: true });\n}\n"]}
+{"version":3,"file":"devfile.js","sourceRoot":"","sources":["../../src/review/devfile.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,2EAA2E;AAC3E,2EAA2E;AAC3E,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEpF,OAAO,IAAI,MAAM,WAAW,CAAC;AAY7B,qCAAqC;AACrC,MAAM,UAAU,WAAW,CAAC,UAAkB;IAC5C,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;AACvD,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,OAAO,CAAC,OAAoB,EAAE,OAAyC;IACrF,IAAI,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC;IAC3B,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,IAAI,GAAG,WAAW,CAAC;SAC5E,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,IAAI,GAAG,IAAI,IAAI,GAAG,CAAC;IAChD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,GAAG,CAAC;IAC5E,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,MAAM,IAAI,IAAI,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;AACpH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,UAAkB,EAAE,IAAa;IAC5D,MAAM,MAAM,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;IACvC,KAAK,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC;QAChD,IAAI,SAAS,CAAC,EAAE,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,cAAc,EAAE,EAAE,CAAC;YAC/D,MAAM,IAAI,KAAK,CAAC,GAAG,EAAE,8DAA8D,CAAC,CAAC;QACvF,CAAC;IACH,CAAC;IACD,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACrD,aAAa,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;AAC9D,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,aAAa,CAAC,UAAkB,EAAE,GAAW;IAC3D,MAAM,MAAM,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;IACvC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAqB,CAAC;QAC7E,IAAI,OAAO,CAAC,GAAG,KAAK,GAAG;YAAE,OAAO;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IACD,MAAM,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAClC,CAAC","sourcesContent":["// `.ascribe/dev.json`: where the dev server is, for the editor's Open Site\n// Preview. Written when the server starts, removed when it stops. A server\n// that crashed leaves it behind, so a reader checks the URL answers first.\nimport { lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from \"node:fs\";\nimport type { AddressInfo } from \"node:net\";\nimport path from \"node:path\";\n\n/** What `dev.json` holds. */\nexport interface DevFile {\n  /** The site's address: origin and base path, `http://localhost:4321/docs/`. */\n  url: string;\n  /** The build the dev server shows. */\n  build: string;\n  /** The dev server's process, so another server's file isn't removed. */\n  pid: number;\n}\n\n/** `<project>/.ascribe/dev.json`. */\nexport function devFilePath(projectDir: string): string {\n  return path.join(projectDir, \".ascribe\", \"dev.json\");\n}\n\n/** The site's address from the server's: a wildcard or loopback host is `localhost`. */\nexport function siteUrl(address: AddressInfo, options: { https: boolean; base: string }): string {\n  let host = address.address;\n  if ([\"::\", \"0.0.0.0\", \"::1\", \"\", \"localhost\"].includes(host)) host = \"localhost\";\n  else if (host.includes(\":\")) host = `[${host}]`;\n  const base = options.base.endsWith(\"/\") ? options.base : `${options.base}/`;\n  return `${options.https ? \"https\" : \"http\"}://${host}:${address.port}${base.startsWith(\"/\") ? base : `/${base}`}`;\n}\n\n/**\n * Writes `dev.json`. A failure is the caller's to log: it only costs the editor its link.\n * `.ascribe` or `dev.json` that's a link (a symbolic link, or a junction on Windows, which\n * Node's `lstat` reports as one) is refused, not written through: a committed link could\n * lead anywhere.\n */\nexport function writeDevFile(projectDir: string, file: DevFile): void {\n  const target = devFilePath(projectDir);\n  for (const at of [path.dirname(target), target]) {\n    if (lstatSync(at, { throwIfNoEntry: false })?.isSymbolicLink()) {\n      throw new Error(`${at} is a link; replace it with a folder or a file, or remove it`);\n    }\n  }\n  mkdirSync(path.dirname(target), { recursive: true });\n  writeFileSync(target, `${JSON.stringify(file, null, 2)}\\n`);\n}\n\n/** Removes `dev.json` if this process wrote it. */\nexport function removeDevFile(projectDir: string, pid: number): void {\n  const target = devFilePath(projectDir);\n  try {\n    const current = JSON.parse(readFileSync(target, \"utf8\")) as Partial<DevFile>;\n    if (current.pid !== pid) return;\n  } catch {\n    return;\n  }\n  rmSync(target, { force: true });\n}\n"]}

package/dist/review/diff.d.ts

@@ -19,3 +19,16 @@ export declare function runDiff(options: {
 }): Promise<DiffResult>;
 /** The build's part of `ascribe diff --format json`'s output. */
 export declare function parseDiff(json: string, build: string): DiffResult;
+/**
+ * `ascribe diff --format prompt`'s prompt about a page, or a fragment's reach,
+ * at a content path; `undefined` when it didn't change. Rejects with
+ * `ascribe diff`'s reason as the message.
+ */
+export declare function runPrompt(options: {
+    binary: string;
+    configPath: string;
+    build: string;
+    cwd: string;
+    base: string | undefined;
+    path: string;
+}): Promise<string | undefined>;

package/dist/review/diff.js

@@ -1,4 +1,5 @@
-// Running `ascribe diff --format json` for the integration's build.
+// Running `ascribe diff` for the integration's build: its changes as JSON, and
+// its agent prompts.
 import { execFile } from "node:child_process";
 /**
  * Compares the build's pages with `base` (the default branch when it's
@@ -45,4 +46,36 @@ export function parseDiff(json, build) {
     const errors = typeof report.working_tree_errors === "number" ? report.working_tree_errors : 0;
     return { base: report.base, pages, errors };
 }
+/**
+ * `ascribe diff --format prompt`'s prompt about a page, or a fragment's reach,
+ * at a content path; `undefined` when it didn't change. Rejects with
+ * `ascribe diff`'s reason as the message.
+ */
+export function runPrompt(options) {
+    const args = [
+        "diff",
+        "--format",
+        "prompt",
+        "--build",
+        options.build,
+        "--config",
+        options.configPath,
+        "--color",
+        "never",
+    ];
+    if (options.base !== undefined)
+        args.push("--base", options.base);
+    // After `--`: a content path that starts with `-` is still a path.
+    args.push("--", options.path);
+    return new Promise((resolve, reject) => {
+        execFile(options.binary, args, { cwd: options.cwd, maxBuffer: 16 * 1024 * 1024, windowsHide: true }, (error, stdout, stderr) => {
+            if (error !== null) {
+                const reason = stderr.trim();
+                reject(new Error(reason === "" ? error.message : reason, { cause: error }));
+                return;
+            }
+            resolve(stdout === "" ? undefined : stdout);
+        });
+    });
+}
 //# sourceMappingURL=diff.js.map

package/dist/review/diff.js.map

@@ -1 +1 @@
-{"version":3,"file":"diff.js","sourceRoot":"","sources":["../../src/review/diff.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAY9C;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,OAMvB;IACC,MAAM,IAAI,GAAG;QACX,MAAM;QACN,UAAU;QACV,MAAM;QACN,SAAS;QACT,OAAO,CAAC,KAAK;QACb,UAAU;QACV,OAAO,CAAC,UAAU;QAClB,SAAS;QACT,OAAO;KACR,CAAC;IACF,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,QAAQ,CACN,OAAO,CAAC,MAAM,EACd,IAAI,EACJ,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,EACrE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;YACxB,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;gBAC7B,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;gBAC5E,OAAO;YACT,CAAC;YACD,IAAI,CAAC;gBACH,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;YAC5C,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,IAAI,KAAK,CAAC,kDAAkD,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;YACnF,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,KAAa;IACnD,2DAA2D;IAC3D,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAwB,CAAC;IACvD,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/D,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;IACvC,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,EAAE,KAAK,IAAI,EAAE,CAAC;IACxE,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,mBAAmB,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/F,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAC9C,CAAC","sourcesContent":["// Running `ascribe diff --format json` for the integration's build.\nimport { execFile } from \"node:child_process\";\nimport type { DiffReport } from \"../shapes.js\";\nimport type { BaseInfo, PageDiff } from \"./protocol.js\";\n\n/** One build's changes against a base. */\nexport interface DiffResult {\n  base: BaseInfo;\n  pages: PageDiff[];\n  /** How many errors `ascribe check` finds in the working tree for the build. */\n  errors: number;\n}\n\n/**\n * Compares the build's pages with `base` (the default branch when it's\n * `undefined`). Rejects with `ascribe diff`'s reason as the message.\n */\nexport function runDiff(options: {\n  binary: string;\n  configPath: string;\n  build: string;\n  cwd: string;\n  base: string | undefined;\n}): Promise<DiffResult> {\n  const args = [\n    \"diff\",\n    \"--format\",\n    \"json\",\n    \"--build\",\n    options.build,\n    \"--config\",\n    options.configPath,\n    \"--color\",\n    \"never\",\n  ];\n  if (options.base !== undefined) args.push(\"--base\", options.base);\n  return new Promise((resolve, reject) => {\n    execFile(\n      options.binary,\n      args,\n      { cwd: options.cwd, maxBuffer: 256 * 1024 * 1024, windowsHide: true },\n      (error, stdout, stderr) => {\n        if (error !== null) {\n          const reason = stderr.trim();\n          reject(new Error(reason === \"\" ? error.message : reason, { cause: error }));\n          return;\n        }\n        try {\n          resolve(parseDiff(stdout, options.build));\n        } catch (cause) {\n          reject(new Error(\"`ascribe diff` wrote output that isn't its JSON.\", { cause }));\n        }\n      },\n    );\n  });\n}\n\n/** The build's part of `ascribe diff --format json`'s output. */\nexport function parseDiff(json: string, build: string): DiffResult {\n  // Checked as far as telling a diff report from other JSON.\n  const report = JSON.parse(json) as Partial<DiffReport>;\n  if (report.base === undefined || !Array.isArray(report.builds)) {\n    throw new Error(\"not a diff report\");\n  }\n  const pages = report.builds.find((b) => b.build === build)?.pages ?? [];\n  const errors = typeof report.working_tree_errors === \"number\" ? report.working_tree_errors : 0;\n  return { base: report.base, pages, errors };\n}\n"]}
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../../src/review/diff.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,qBAAqB;AACrB,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAY9C;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,OAMvB;IACC,MAAM,IAAI,GAAG;QACX,MAAM;QACN,UAAU;QACV,MAAM;QACN,SAAS;QACT,OAAO,CAAC,KAAK;QACb,UAAU;QACV,OAAO,CAAC,UAAU;QAClB,SAAS;QACT,OAAO;KACR,CAAC;IACF,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,QAAQ,CACN,OAAO,CAAC,MAAM,EACd,IAAI,EACJ,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,EACrE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;YACxB,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;gBAC7B,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;gBAC5E,OAAO;YACT,CAAC;YACD,IAAI,CAAC;gBACH,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;YAC5C,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,IAAI,KAAK,CAAC,kDAAkD,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;YACnF,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,KAAa;IACnD,2DAA2D;IAC3D,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAwB,CAAC;IACvD,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/D,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;IACvC,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,EAAE,KAAK,IAAI,EAAE,CAAC;IACxE,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,mBAAmB,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/F,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,OAOzB;IACC,MAAM,IAAI,GAAG;QACX,MAAM;QACN,UAAU;QACV,QAAQ;QACR,SAAS;QACT,OAAO,CAAC,KAAK;QACb,UAAU;QACV,OAAO,CAAC,UAAU;QAClB,SAAS;QACT,OAAO;KACR,CAAC;IACF,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,mEAAmE;IACnE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,QAAQ,CACN,OAAO,CAAC,MAAM,EACd,IAAI,EACJ,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,EACpE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;YACxB,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;gBAC7B,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;gBAC5E,OAAO;YACT,CAAC;YACD,OAAO,CAAC,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QAC9C,CAAC,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["// Running `ascribe diff` for the integration's build: its changes as JSON, and\n// its agent prompts.\nimport { execFile } from \"node:child_process\";\nimport type { DiffReport } from \"../shapes.js\";\nimport type { BaseInfo, PageDiff } from \"./protocol.js\";\n\n/** One build's changes against a base. */\nexport interface DiffResult {\n  base: BaseInfo;\n  pages: PageDiff[];\n  /** How many errors `ascribe check` finds in the working tree for the build. */\n  errors: number;\n}\n\n/**\n * Compares the build's pages with `base` (the default branch when it's\n * `undefined`). Rejects with `ascribe diff`'s reason as the message.\n */\nexport function runDiff(options: {\n  binary: string;\n  configPath: string;\n  build: string;\n  cwd: string;\n  base: string | undefined;\n}): Promise<DiffResult> {\n  const args = [\n    \"diff\",\n    \"--format\",\n    \"json\",\n    \"--build\",\n    options.build,\n    \"--config\",\n    options.configPath,\n    \"--color\",\n    \"never\",\n  ];\n  if (options.base !== undefined) args.push(\"--base\", options.base);\n  return new Promise((resolve, reject) => {\n    execFile(\n      options.binary,\n      args,\n      { cwd: options.cwd, maxBuffer: 256 * 1024 * 1024, windowsHide: true },\n      (error, stdout, stderr) => {\n        if (error !== null) {\n          const reason = stderr.trim();\n          reject(new Error(reason === \"\" ? error.message : reason, { cause: error }));\n          return;\n        }\n        try {\n          resolve(parseDiff(stdout, options.build));\n        } catch (cause) {\n          reject(new Error(\"`ascribe diff` wrote output that isn't its JSON.\", { cause }));\n        }\n      },\n    );\n  });\n}\n\n/** The build's part of `ascribe diff --format json`'s output. */\nexport function parseDiff(json: string, build: string): DiffResult {\n  // Checked as far as telling a diff report from other JSON.\n  const report = JSON.parse(json) as Partial<DiffReport>;\n  if (report.base === undefined || !Array.isArray(report.builds)) {\n    throw new Error(\"not a diff report\");\n  }\n  const pages = report.builds.find((b) => b.build === build)?.pages ?? [];\n  const errors = typeof report.working_tree_errors === \"number\" ? report.working_tree_errors : 0;\n  return { base: report.base, pages, errors };\n}\n\n/**\n * `ascribe diff --format prompt`'s prompt about a page, or a fragment's reach,\n * at a content path; `undefined` when it didn't change. Rejects with\n * `ascribe diff`'s reason as the message.\n */\nexport function runPrompt(options: {\n  binary: string;\n  configPath: string;\n  build: string;\n  cwd: string;\n  base: string | undefined;\n  path: string;\n}): Promise<string | undefined> {\n  const args = [\n    \"diff\",\n    \"--format\",\n    \"prompt\",\n    \"--build\",\n    options.build,\n    \"--config\",\n    options.configPath,\n    \"--color\",\n    \"never\",\n  ];\n  if (options.base !== undefined) args.push(\"--base\", options.base);\n  // After `--`: a content path that starts with `-` is still a path.\n  args.push(\"--\", options.path);\n  return new Promise((resolve, reject) => {\n    execFile(\n      options.binary,\n      args,\n      { cwd: options.cwd, maxBuffer: 16 * 1024 * 1024, windowsHide: true },\n      (error, stdout, stderr) => {\n        if (error !== null) {\n          const reason = stderr.trim();\n          reject(new Error(reason === \"\" ? error.message : reason, { cause: error }));\n          return;\n        }\n        resolve(stdout === \"\" ? undefined : stdout);\n      },\n    );\n  });\n}\n"]}

package/dist/review/protocol.d.ts

@@ -1,4 +1,5 @@
 import type { BaseInfo, PageDiff } from "../shapes.js";
+import type { FormattedPiece } from "@ascribed/review/overlay";
 /** `ascribe diff --format json`'s types: a changed page, its block changes, and the base. */
 export type { BaseInfo, Change, Counts, PageDiff } from "../shapes.js";
 /** The toolbar app's id, also the prefix of its events. */
@@ -22,9 +23,13 @@ export interface Result {
         code?: string;
     };
 }
-/** A changed page in the list: without its changes, and with its title when the build has it. */
+/**
+ * A changed page in the list: without its changes, and with its title when
+ * the build has it, formatted when its field sets `inline = "code"`.
+ */
 export type ChangedPage = Omit<PageDiff, "changes"> & {
     title: string | null;
+    formatted_title: FormattedPiece[] | null;
 };
 /** How the checkout's `HEAD` relates to the pull request's head commit. */
 export type LocalState = "same" | "behind" | "ahead" | "diverged" | "missing";

package/dist/review/protocol.js.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/review/protocol.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,wEAAwE;AACxE,EAAE;AACF,8EAA8E;AAC9E,yEAAyE;AACzE,8EAA8E;AAC9E,wEAAwE;AACxE,mCAAmC;AAOnC,2DAA2D;AAC3D,MAAM,CAAC,MAAM,MAAM,GAAG,gBAAgB,CAAC;AACvC,MAAM,CAAC,MAAM,aAAa,GAAG,wBAAwB,CAAC;AACtD,MAAM,CAAC,MAAM,YAAY,GAAG,uBAAuB,CAAC;AACpD,MAAM,CAAC,MAAM,aAAa,GAAG,wBAAwB,CAAC","sourcesContent":["// The messages between the toolbar app (in the page) and the dev server,\n// over Astro's dev toolbar channel. Types only: both sides import them.\n//\n// The page sends `ascribe:review:request` with `{ tab, id, method, params }`;\n// the server answers that page with `ascribe:review:result` and the same\n// `tab` and `id`. When a page's request changes the threads, or review stops,\n// the server tells every page with `ascribe:review:changed`, naming the\n// `from` tab, which already knows.\n\nimport type { BaseInfo, PageDiff } from \"../shapes.js\";\n\n/** `ascribe diff --format json`'s types: a changed page, its block changes, and the base. */\nexport type { BaseInfo, Change, Counts, PageDiff } from \"../shapes.js\";\n\n/** The toolbar app's id, also the prefix of its events. */\nexport const APP_ID = \"ascribe:review\";\nexport const REQUEST_EVENT = \"ascribe:review:request\";\nexport const RESULT_EVENT = \"ascribe:review:result\";\nexport const CHANGED_EVENT = \"ascribe:review:changed\";\n\nexport interface Request {\n  /** The page's own id, made when it loads. */\n  tab: string;\n  id: number;\n  method: string;\n  params: Record<string, unknown>;\n}\n\nexport interface Result {\n  tab: string;\n  id: number;\n  result?: unknown;\n  error?: { message: string; code?: string };\n}\n\n/** A changed page in the list: without its changes, and with its title when the build has it. */\nexport type ChangedPage = Omit<PageDiff, \"changes\"> & { title: string | null };\n\n/** How the checkout's `HEAD` relates to the pull request's head commit. */\nexport type LocalState = \"same\" | \"behind\" | \"ahead\" | \"diverged\" | \"missing\";\n\n/** The review threads: on, or why not, with a sentence to show. */\nexport type ThreadsState =\n  | {\n      state: \"on\";\n      pullRequest: { number: number; url: string; baseRefName: string };\n      local: { state: LocalState; behind: number; ahead: number };\n    }\n  /** No pull request, no GitHub CLI, no sign-in, a channel other pages could use, or a failure. */\n  | {\n      state: \"no-pull-request\" | \"gh-missing\" | \"signed-out\" | \"unprotected\" | \"error\";\n      message: string;\n    };\n\n/** `status`'s answer. */\nexport interface Status {\n  on: boolean;\n}\n\n/** `page`'s answer: what the app shows for the page at a route. */\nexport interface PageView {\n  /** `\"page\"` for a page of the Ascribe build, `\"not-page\"` for the site's own routes. */\n  kind: \"page\" | \"not-page\";\n  /** The page's content path; `null` for a route that isn't one. */\n  path: string | null;\n  /** The page's changes; `null` when it didn't change. */\n  page: PageDiff | null;\n  base: BaseInfo | null;\n  /** Why the changes couldn't be read, when they couldn't. */\n  problem: string | null;\n  /** How many errors `ascribe check` finds in the working tree for the build. */\n  errors: number;\n  threads: ThreadsState;\n  /** The build's changed pages, in path order. */\n  changedPages: ChangedPage[];\n  /** The content root, absolute, and the platform's path separator: for opening a source file. */\n  contentRoot: string;\n  separator: string;\n}\n"]}
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/review/protocol.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,wEAAwE;AACxE,EAAE;AACF,8EAA8E;AAC9E,yEAAyE;AACzE,8EAA8E;AAC9E,wEAAwE;AACxE,mCAAmC;AAQnC,2DAA2D;AAC3D,MAAM,CAAC,MAAM,MAAM,GAAG,gBAAgB,CAAC;AACvC,MAAM,CAAC,MAAM,aAAa,GAAG,wBAAwB,CAAC;AACtD,MAAM,CAAC,MAAM,YAAY,GAAG,uBAAuB,CAAC;AACpD,MAAM,CAAC,MAAM,aAAa,GAAG,wBAAwB,CAAC","sourcesContent":["// The messages between the toolbar app (in the page) and the dev server,\n// over Astro's dev toolbar channel. Types only: both sides import them.\n//\n// The page sends `ascribe:review:request` with `{ tab, id, method, params }`;\n// the server answers that page with `ascribe:review:result` and the same\n// `tab` and `id`. When a page's request changes the threads, or review stops,\n// the server tells every page with `ascribe:review:changed`, naming the\n// `from` tab, which already knows.\n\nimport type { BaseInfo, PageDiff } from \"../shapes.js\";\nimport type { FormattedPiece } from \"@ascribed/review/overlay\";\n\n/** `ascribe diff --format json`'s types: a changed page, its block changes, and the base. */\nexport type { BaseInfo, Change, Counts, PageDiff } from \"../shapes.js\";\n\n/** The toolbar app's id, also the prefix of its events. */\nexport const APP_ID = \"ascribe:review\";\nexport const REQUEST_EVENT = \"ascribe:review:request\";\nexport const RESULT_EVENT = \"ascribe:review:result\";\nexport const CHANGED_EVENT = \"ascribe:review:changed\";\n\nexport interface Request {\n  /** The page's own id, made when it loads. */\n  tab: string;\n  id: number;\n  method: string;\n  params: Record<string, unknown>;\n}\n\nexport interface Result {\n  tab: string;\n  id: number;\n  result?: unknown;\n  error?: { message: string; code?: string };\n}\n\n/**\n * A changed page in the list: without its changes, and with its title when\n * the build has it, formatted when its field sets `inline = \"code\"`.\n */\nexport type ChangedPage = Omit<PageDiff, \"changes\"> & {\n  title: string | null;\n  formatted_title: FormattedPiece[] | null;\n};\n\n/** How the checkout's `HEAD` relates to the pull request's head commit. */\nexport type LocalState = \"same\" | \"behind\" | \"ahead\" | \"diverged\" | \"missing\";\n\n/** The review threads: on, or why not, with a sentence to show. */\nexport type ThreadsState =\n  | {\n      state: \"on\";\n      pullRequest: { number: number; url: string; baseRefName: string };\n      local: { state: LocalState; behind: number; ahead: number };\n    }\n  /** No pull request, no GitHub CLI, no sign-in, a channel other pages could use, or a failure. */\n  | {\n      state: \"no-pull-request\" | \"gh-missing\" | \"signed-out\" | \"unprotected\" | \"error\";\n      message: string;\n    };\n\n/** `status`'s answer. */\nexport interface Status {\n  on: boolean;\n}\n\n/** `page`'s answer: what the app shows for the page at a route. */\nexport interface PageView {\n  /** `\"page\"` for a page of the Ascribe build, `\"not-page\"` for the site's own routes. */\n  kind: \"page\" | \"not-page\";\n  /** The page's content path; `null` for a route that isn't one. */\n  path: string | null;\n  /** The page's changes; `null` when it didn't change. */\n  page: PageDiff | null;\n  base: BaseInfo | null;\n  /** Why the changes couldn't be read, when they couldn't. */\n  problem: string | null;\n  /** How many errors `ascribe check` finds in the working tree for the build. */\n  errors: number;\n  threads: ThreadsState;\n  /** The build's changed pages, in path order. */\n  changedPages: ChangedPage[];\n  /** The content root, absolute, and the platform's path separator: for opening a source file. */\n  contentRoot: string;\n  separator: string;\n}\n"]}

package/dist/review/routes.d.ts

@@ -1,3 +1,4 @@
+import type { FormattedPiece } from "@ascribed/review/overlay";
 /** A route as compared: decoded, without a trailing `/` (except the root's). */
 export declare function normalizeRoute(route: string): string;
 /** A page of the build, as its JSON output names it. */
@@ -5,6 +6,8 @@ export interface RoutedPage {
     /** The content path. */
     path: string;
     title: string | null;
+    /** The title formatted, when its field sets `inline = "code"`. */
+    formatted_title: FormattedPiece[] | null;
 }
 /**
  * Every page of the build's JSON output (`<output-dir>/<build>/json/`), by