srcpack 0.2.0 → 1.0.0

package/src/linear.ts

@@ -0,0 +1,368 @@
+// SPDX-License-Identifier: MIT
+
+import type { LinearSourceInput } from "./config.ts";
+
+const API_URL = "https://api.linear.app/graphql";
+
+/** A stalled connection shouldn't leave the CLI hanging with a spinner up. */
+const TIMEOUT_MS = 30_000;
+
+/** Personal API key: Linear → Settings → Security & access → Personal API keys. */
+const TOKEN_ENV = "LINEAR_API_KEY";
+
+/**
+ * Linear charges query complexity as page size × selected fields, and the issue
+ * selection below is wide enough that asking for its 250 maximum is rejected
+ * outright as "Query too complex".
+ */
+const PAGE = 50;
+
+/**
+ * Terminal workflow state types, excluded unless asked for. `duplicate` is easy
+ * to miss — it is a state type of its own, not a state name under `canceled`,
+ * so omitting it leaks duplicates into a bundle meant to be non-terminal.
+ */
+const CLOSED_STATES = ["completed", "canceled", "duplicate"];
+
+/** Linear encodes priority as 0-4; 0 sorts as "no priority", not "lowest". */
+const PRIORITY = ["None", "Urgent", "High", "Medium", "Low"];
+
+export class LinearError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "LinearError";
+  }
+}
+
+interface Issue {
+  identifier: string;
+  title: string;
+  description: string | null;
+  priority: number;
+  estimate: number | null;
+  dueDate: string | null;
+  url: string;
+  createdAt: string;
+  updatedAt: string;
+  state: { name: string; type: string };
+  labels: { nodes: { name: string; parent: { name: string } | null }[] };
+  project: { name: string } | null;
+  projectMilestone: { name: string } | null;
+  parent: { identifier: string } | null;
+  assignee: { name: string } | null;
+}
+
+interface Page<T> {
+  nodes: T[];
+  pageInfo: { hasNextPage: boolean; endCursor: string | null };
+}
+
+function requireToken(): string {
+  // Trimmed: a key read from a file or piped through shell tooling arrives with
+  // a trailing newline, which Linear answers with a bare "not authorized".
+  const token = process.env[TOKEN_ENV]?.trim();
+  if (!token) {
+    throw new LinearError(
+      `${TOKEN_ENV} is not set. Create a personal API key in Linear ` +
+        "(Settings → Security & access → Personal API keys).",
+    );
+  }
+  return token;
+}
+
+async function graphql<T>(
+  query: string,
+  variables: Record<string, unknown>,
+  token: string,
+): Promise<T> {
+  let response: Response;
+  try {
+    response = await fetch(API_URL, {
+      method: "POST",
+      headers: { authorization: token, "content-type": "application/json" },
+      body: JSON.stringify({ query, variables }),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch (error) {
+    // A timeout arrives as a DOMException, whose message ("The operation was
+    // aborted due to timeout") reads like an internal error rather than advice
+    if ((error as Error).name === "TimeoutError") {
+      throw new LinearError(
+        `Linear API request timed out after ${TIMEOUT_MS / 1000}s.`,
+      );
+    }
+    throw new LinearError(
+      `Cannot reach the Linear API: ${(error as Error).message}`,
+    );
+  }
+
+  if (response.status === 401 || response.status === 403) {
+    throw new LinearError(
+      `${TOKEN_ENV} was rejected by Linear (not authorized).`,
+    );
+  }
+
+  let body: { data?: T; errors?: { message: string }[] };
+  try {
+    body = (await response.json()) as typeof body;
+  } catch {
+    throw new LinearError(`Linear API returned ${response.status}.`);
+  }
+
+  // Linear answers 200 with an `errors` array, so status alone proves nothing.
+  if (body.errors?.length) {
+    throw new LinearError(body.errors.map((e) => e.message).join("; "));
+  }
+  if (!response.ok || !body.data) {
+    throw new LinearError(`Linear API returned ${response.status}.`);
+  }
+  return body.data;
+}
+
+/** Fill in the shorthand form and the `includeClosed` default. */
+function normalize(source: LinearSourceInput): {
+  team: string;
+  project?: string;
+  includeClosed: boolean;
+} {
+  if (typeof source === "string") {
+    return { team: source, includeClosed: false };
+  }
+  return {
+    team: source.team,
+    project: source.project,
+    includeClosed: source.includeClosed ?? false,
+  };
+}
+
+/**
+ * Confirm the team exists and resolve the project name to a single id.
+ *
+ * Linear answers an unknown team key with an empty issue list rather than an
+ * error, so without this a typo yields a silently empty bundle — the one
+ * failure mode that looks like success. Project names are neither unique nor
+ * stable, so they are resolved to an id within the team and required to match
+ * exactly one project; filtering issues by name would silently union two.
+ */
+async function resolveScope(
+  team: string,
+  project: string | undefined,
+  token: string,
+): Promise<{ projectId?: string }> {
+  const projects = project
+    ? "projects(filter: { name: { eq: $project } }, first: 2) { nodes { id } }"
+    : "";
+  const query = `
+    query ($team: String!${project ? ", $project: String!" : ""}) {
+      teams(filter: { key: { eq: $team } }, first: 1) {
+        nodes { key ${projects} }
+      }
+    }
+  `;
+  const data = await graphql<{
+    teams: { nodes: { projects?: { nodes: { id: string }[] } }[] };
+  }>(query, project ? { team, project } : { team }, token);
+
+  const found = data.teams.nodes[0];
+  if (!found) {
+    throw new LinearError(
+      `Team "${team}" not found in this Linear workspace. ` +
+        "Use the team key shown in issue identifiers (the ENG in ENG-123).",
+    );
+  }
+  if (!project) return {};
+
+  const matches = found.projects?.nodes ?? [];
+  if (matches.length === 0) {
+    throw new LinearError(`Project "${project}" not found in team "${team}".`);
+  }
+  if (matches.length > 1) {
+    throw new LinearError(
+      `Project "${project}" is ambiguous: team "${team}" has more than one project with that name.`,
+    );
+  }
+  return { projectId: matches[0]!.id };
+}
+
+async function fetchIssues(
+  filter: Record<string, unknown>,
+  token: string,
+): Promise<Issue[]> {
+  // Ordered by `createdAt`, not the `updatedAt` default: a cursor walk is only
+  // stable while the sort key is. An issue edited mid-run reorders an
+  // `updatedAt` list under the cursor, dropping or repeating its neighbours.
+  const query = `
+    query ($cursor: String, $filter: IssueFilter) {
+      issues(first: ${PAGE}, after: $cursor, filter: $filter, orderBy: createdAt) {
+        nodes {
+          identifier
+          title
+          description
+          priority
+          estimate
+          dueDate
+          url
+          createdAt
+          updatedAt
+          state { name type }
+          # A deliberate cap, not pagination: 50 labels is far past what an
+          # issue carries, and each nested page multiplies query complexity
+          labels(first: 50) { nodes { name parent { name } } }
+          project { name }
+          projectMilestone { name }
+          parent { identifier }
+          assignee { name }
+        }
+        pageInfo { hasNextPage endCursor }
+      }
+    }
+  `;
+
+  const issues: Issue[] = [];
+  let cursor: string | null = null;
+  do {
+    const data: { issues: Page<Issue> } = await graphql<{
+      issues: Page<Issue>;
+    }>(query, { cursor, filter }, token);
+    issues.push(...data.issues.nodes);
+    cursor = data.issues.pageInfo.hasNextPage
+      ? data.issues.pageInfo.endCursor
+      : null;
+  } while (cursor);
+
+  return issues;
+}
+
+/**
+ * Issue mentions arrive as ordinary markdown links and need no handling.
+ * Attachments do: an embedded image or video is one long `<linear-embed>` tag
+ * carrying an upload URL and a JSON blob, which burns context for nothing.
+ */
+function stripEmbeds(markdown: string): string {
+  return markdown
+    .replace(/<linear-embed\b[^>]*>.*?<\/linear-embed>/gs, "[embed]")
+    .replace(/<linear-embed\b[^>]*\/?>/g, "[embed]")
+    .trimEnd();
+}
+
+function labelNames(issue: Issue): string[] {
+  return issue.labels.nodes.map((l) =>
+    l.parent ? `${l.parent.name}/${l.name}` : l.name,
+  );
+}
+
+/** The number in `SM-13`, for ordering. Non-numeric suffixes sort last. */
+function issueNumber(issue: Issue): number {
+  const n = Number(issue.identifier.split("-").pop());
+  return Number.isFinite(n) ? n : Number.MAX_SAFE_INTEGER;
+}
+
+/**
+ * A roster of every issue in the bundle, emitted as the first Linear entry.
+ *
+ * The bundle index lists paths, and `linear/issues/SM-13.md` says nothing about
+ * what SM-13 is — so without this a model has to read forty issue bodies to
+ * find the two that matter, and can't answer "what's in progress" at all.
+ *
+ * Rows are ordered by issue number, which the index itself cannot be: it sorts
+ * paths as text, so SM-2 lands between SM-19 and SM-20.
+ */
+function renderSummary(scope: string, issues: Issue[]): string {
+  const tally = new Map<string, number>();
+  for (const issue of issues) {
+    tally.set(issue.state.name, (tally.get(issue.state.name) ?? 0) + 1);
+  }
+  const counts = [...tally]
+    .sort((a, b) => b[1] - a[1])
+    .map(([name, n]) => `${name} ${n}`)
+    .join(" · ");
+
+  const rows = [...issues]
+    .sort((a, b) => issueNumber(a) - issueNumber(b))
+    .map((issue) => {
+      // A title carrying `|` would otherwise split into a phantom column
+      const title = issue.title.replace(/\|/g, "\\|");
+      const priority = PRIORITY[issue.priority] ?? String(issue.priority);
+      return `| ${issue.identifier} | ${issue.state.name} | ${priority} | ${title} |`;
+    });
+
+  return [
+    `# ${scope} — ${issues.length} ${issues.length === 1 ? "issue" : "issues"}`,
+    "",
+    counts,
+    "",
+    "| Issue | State | Priority | Title |",
+    "| --- | --- | --- | --- |",
+    ...rows,
+  ].join("\n");
+}
+
+/** Render one issue as markdown: a title, an aligned field block, the body. */
+function render(issue: Issue): string {
+  const field = (name: string, value: string | null | undefined) =>
+    `${name.padEnd(10)} ${value?.length ? value : "—"}`;
+
+  const description = issue.description?.trim()
+    ? stripEmbeds(issue.description)
+    : "(no description)";
+
+  return [
+    `# ${issue.identifier}  ${issue.title}`,
+    "",
+    field("State", `${issue.state.name} (${issue.state.type})`),
+    field("Priority", PRIORITY[issue.priority] ?? String(issue.priority)),
+    field("Estimate", issue.estimate === null ? null : String(issue.estimate)),
+    field("Labels", labelNames(issue).join(", ")),
+    field("Project", issue.project?.name),
+    field("Milestone", issue.projectMilestone?.name),
+    field("Parent", issue.parent?.identifier),
+    field("Assignee", issue.assignee?.name),
+    field("Due", issue.dueDate),
+    field("Created", issue.createdAt.slice(0, 10)),
+    field("Updated", issue.updatedAt.slice(0, 10)),
+    field("URL", issue.url),
+    "",
+    description,
+  ].join("\n");
+}
+
+/**
+ * Resolve a `linear` bundle source to one virtual file per issue.
+ *
+ * Paths are namespaced under `linear/issues/` so they sort together, read as
+ * files in the index, and can be filtered with ordinary `!` exclusions.
+ *
+ * The return type is structural rather than `Entry` from `bundle.ts`: a source
+ * shouldn't depend on the module that orchestrates it.
+ */
+export async function resolveLinearSource(
+  source: LinearSourceInput,
+): Promise<{ path: string; content: string }[]> {
+  const { team, project, includeClosed } = normalize(source);
+  const token = requireToken();
+
+  const { projectId } = await resolveScope(team, project, token);
+
+  const filter: Record<string, unknown> = { team: { key: { eq: team } } };
+  if (projectId) filter.project = { id: { eq: projectId } };
+  if (!includeClosed) filter.state = { type: { nin: CLOSED_STATES } };
+
+  const issues = await fetchIssues(filter, token);
+  if (issues.length === 0) return [];
+
+  // Sorts ahead of `linear/issues/…` because "." precedes "/", so the roster is
+  // the first Linear entry a reader meets. Subject to the same collision check
+  // and `!` exclusions as any other entry.
+  const scope = project ? `${team} / ${project}` : team;
+  const entries = [
+    { path: "linear/issues.md", content: renderSummary(scope, issues) },
+  ];
+
+  for (const issue of issues) {
+    entries.push({
+      path: `linear/issues/${issue.identifier}.md`,
+      content: render(issue),
+    });
+  }
+  return entries;
+}

package/src/plan.ts

@@ -0,0 +1,238 @@
+// SPDX-License-Identifier: MIT
+
+import { basename, dirname, join, relative, resolve } from "node:path";
+import type { BundleResult } from "./bundle.ts";
+import { ConfigError, type BundleConfig } from "./config.ts";
+import { entryPath, pathKey, physicalPath } from "./fs.ts";
+import {
+  isImageOf,
+  toScreenshotTarget,
+  type CapturedPage,
+  type ScreenshotTarget,
+} from "./screenshot.ts";
+
+// Check output destinations before resolving sources or launching a browser.
+// Retain each active plan through writing, reporting and upload.
+
+/** Where a bundle writes. */
+export interface PlannedBundle {
+  name: string;
+  source: BundleConfig;
+  /** Absolute path of the text output. Absent for a screenshot-only bundle. */
+  text?: { outfile: string };
+  /** Page to capture into `<dir>/<name>-NN.png`. */
+  images?: { target: ScreenshotTarget; dir: string };
+}
+
+/** What a bundle produced, ready to write. */
+export interface ResolvedBundle {
+  plan: PlannedBundle;
+  text?: BundleResult;
+  images?: CapturedPage;
+}
+
+export interface BundleSelection {
+  /** Bundles this run builds, in the order named or configured. */
+  names: string[];
+  /** On-demand bundles a full run left out. Empty when bundles are named. */
+  skipped: string[];
+}
+
+function isOnDemand(config: BundleConfig): boolean {
+  return (
+    typeof config === "object" &&
+    !Array.isArray(config) &&
+    config.onDemand === true
+  );
+}
+
+/**
+ * Pick the bundles a run builds. Naming a bundle always builds it; a full run
+ * builds everything not marked `onDemand`.
+ */
+export function selectBundles(
+  bundles: Record<string, BundleConfig>,
+  requested: string[],
+): BundleSelection {
+  for (const name of requested) {
+    // hasOwn, not `in`: `srcpack toString` would otherwise find Object.prototype
+    if (!Object.hasOwn(bundles, name)) {
+      throw new ConfigError(`Unknown bundle: ${name}`);
+    }
+  }
+  if (requested.length) {
+    return { names: [...new Set(requested)], skipped: [] };
+  }
+
+  const names: string[] = [];
+  const skipped: string[] = [];
+  for (const [name, config] of Object.entries(bundles)) {
+    (isOnDemand(config) ? skipped : names).push(name);
+  }
+  return { names, skipped };
+}
+
+export interface OutputPlan {
+  /** The bundles this run builds, in order. */
+  bundles: PlannedBundle[];
+  /**
+   * Absolute paths srcpack writes, never to be bundled: every configured text
+   * output and every active one, each in lexical and entry spelling. A glob
+   * rooted at a symlink yields lexical paths, one rooted at the real directory
+   * yields physical ones, and either can name a file the previous run wrote.
+   *
+   * Image families need no entry: they always live in outDir, which the CLI
+   * excludes, and when outDir holds the root a PNG is skipped as binary anyway.
+   */
+  ownOutputs: string[];
+}
+
+function planBundle(
+  name: string,
+  source: BundleConfig,
+  root: string,
+  outDir: string,
+): PlannedBundle {
+  const object =
+    typeof source === "object" && !Array.isArray(source) ? source : undefined;
+  const plan: PlannedBundle = { name, source };
+  // Every bundle writes text unless a screenshot is all it declares
+  if (!object || object.include || object.linear) {
+    const outfile = object?.outfile ?? join(outDir, `${name}.txt`);
+    plan.text = { outfile: resolve(root, outfile) };
+  }
+  // Keep image cleanup within outDir, independent of any text outfile.
+  if (object?.screenshot) {
+    plan.images = {
+      target: toScreenshotTarget(object.screenshot),
+      dir: resolve(root, outDir),
+    };
+  }
+  return plan;
+}
+
+/**
+ * A claim on a destination: a text file, or an image family — a directory
+ * plus a name prefix. Compared folded (`pathKey`) and physically.
+ *
+ * A text file's directory is its entry path's parent, as for any output. A
+ * family's directory resolves fully: it is an ancestor of every PNG, and
+ * `rename` replaces only the last component (ADR 004).
+ */
+interface Claim {
+  owner: string;
+  kind: "file" | "family";
+  dir: string;
+  /** Folded file name, or folded bundle name for a family. */
+  name: string;
+  /** Absolute path shown in a collision message. */
+  display: string;
+}
+
+function overlaps(a: Claim, b: Claim): boolean {
+  if (a.dir !== b.dir) return false;
+  if (a.kind === b.kind) return a.name === b.name;
+  const [file, family] = a.kind === "file" ? [a, b] : [b, a];
+  return isImageOf(family.name, file.name);
+}
+
+/** `entry` is the text output's entry path, resolved once by the caller. */
+async function claimsOf(
+  plan: PlannedBundle,
+  entry: string | undefined,
+): Promise<Claim[]> {
+  const claims: Claim[] = [];
+  if (plan.text && entry) {
+    claims.push({
+      owner: plan.name,
+      kind: "file",
+      dir: pathKey(dirname(entry)),
+      name: pathKey(basename(entry)),
+      display: plan.text.outfile,
+    });
+  }
+  if (plan.images) {
+    claims.push({
+      owner: plan.name,
+      kind: "family",
+      dir: pathKey(await physicalPath(plan.images.dir)),
+      name: pathKey(plan.name),
+      display: join(plan.images.dir, `${plan.name}-NN.png`),
+    });
+  }
+  return claims;
+}
+
+function collision(first: Claim, second: Claim, root: string): ConfigError {
+  // Name the later bundle's destination, unless only the earlier one is a file:
+  // a file is what the user can change
+  const { display } =
+    first.kind === "file" && second.kind === "family" ? first : second;
+  const where = relative(root, display) || display;
+  if (first.owner === second.owner) {
+    return new ConfigError(
+      `Bundle "${first.owner}" writes its text and its images to "${where}". Give it another outfile.`,
+    );
+  }
+  return new ConfigError(
+    `Bundles "${first.owner}" and "${second.owner}" both write to "${where}". ` +
+      (first.kind === "family" && second.kind === "family"
+        ? "Rename one of them."
+        : "Give one of them its own outfile."),
+  );
+}
+
+/**
+ * Derive where every bundle writes and reject two bundles sharing a file.
+ *
+ * Resolve directory aliases and compare destinations with `pathKey` to prevent
+ * silent overwrites. Text files also collide with numbered images in the same
+ * directory, including their own bundle's images.
+ *
+ * Configured bundles are checked against each other on every run, so a config
+ * error doesn't depend on what was asked for. Active bundles — the ones `active`
+ * names, ad-hoc included — are checked against configured bundles of a
+ * different name: an ad-hoc bundle shadows a configured bundle of its own name
+ * (`--staged` over a `staged` bundle) but never overwrites another's output.
+ * Active bundles need no check among themselves: they are either configured,
+ * and already checked, or a single ad-hoc bundle.
+ */
+export async function planOutputs(
+  root: string,
+  outDir: string,
+  configured: Record<string, BundleConfig>,
+  active: [name: string, source: BundleConfig][],
+): Promise<OutputPlan> {
+  const ownOutputs = new Set<string>();
+  const claims: Claim[] = [];
+
+  const claim = async (plan: PlannedBundle, shadowsOwnName: boolean) => {
+    const entry = plan.text && (await entryPath(plan.text.outfile));
+    for (const next of await claimsOf(plan, entry)) {
+      const taken = claims.find(
+        (prior) =>
+          !(shadowsOwnName && prior.owner === next.owner) &&
+          overlaps(prior, next),
+      );
+      if (taken) throw collision(taken, next, root);
+      claims.push(next);
+    }
+    if (plan.text && entry) {
+      ownOutputs.add(plan.text.outfile);
+      ownOutputs.add(entry);
+    }
+  };
+
+  for (const [name, source] of Object.entries(configured)) {
+    await claim(planBundle(name, source, root, outDir), false);
+  }
+
+  const bundles: PlannedBundle[] = [];
+  for (const [name, source] of active) {
+    const plan = planBundle(name, source, root, outDir);
+    await claim(plan, true);
+    bundles.push(plan);
+  }
+
+  return { bundles, ownOutputs: [...ownOutputs] };
+}