@shortlink-org/portolan 0.1.0

package/scripts/manifest.test.mjs

@@ -0,0 +1,148 @@
+// The manifest is checked against the schema the plugins describe, so these
+// run against the committed schema/portolan.schema.json rather than a fixture:
+// what is worth asserting is that the real document catches a real typo.
+
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { loadManifest, stepKeys } from "./manifest.mjs";
+
+const dir = mkdtempSync(join(tmpdir(), "portolan-manifest-"));
+
+/** Writes a manifest to a scratch file and validates it. */
+function check(manifest) {
+  const path = join(dir, `${Math.random().toString(36).slice(2)}.json`);
+  writeFileSync(path, JSON.stringify(manifest));
+
+  return loadManifest(path).problems;
+}
+
+const good = {
+  sources: ["data/*.json"],
+  projects: [
+    {
+      id: "auth",
+      name: "Authentication",
+      root: "examples/auth",
+      context: "auth",
+      service: "auth",
+    },
+  ],
+  plugins: [{ name: "go-domain", process: { command: "go", args: ["run", "./plugins/extract-go"] } }],
+  extract: [
+    {
+      plugin: "go-domain",
+      in: "examples/auth",
+      out: "examples/auth/portolan",
+      options: { context: "auth", contextSummary: "Who someone is." },
+    },
+  ],
+};
+
+describe("the manifest schema", () => {
+  it("accepts the manifest this repository ships", () => {
+    expect(loadManifest("portolan.json").problems).toEqual([]);
+  });
+
+  it("accepts a well-formed manifest", () => {
+    expect(check(good)).toEqual([]);
+  });
+
+  it("refuses an unstable project id", () => {
+    const problems = check({
+      ...good,
+      projects: [{ ...good.projects[0], id: "Auth Service" }],
+    });
+
+    expect(problems.join("\n")).toContain("projects/0/id");
+  });
+
+  it("names the option a typo was probably meant to be", () => {
+    const problems = check({
+      ...good,
+      extract: [{ ...good.extract[0], options: { context: "auth", contextSummry: "..." } }],
+    });
+
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).toContain("contextSummry");
+    expect(problems[0]).toContain('did you mean "contextSummary"');
+  });
+
+  it("lists the known options when a key resembles nothing", () => {
+    const problems = check({
+      ...good,
+      extract: [{ ...good.extract[0], options: { database: "pg" } }],
+    });
+
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).not.toContain("did you mean");
+    expect(problems[0]).toContain("known: context,");
+  });
+
+  it("refuses an option whose value is not one the plugin accepts", () => {
+    const problems = check({
+      ...good,
+      extract: [{ ...good.extract[0], options: { classification: "essential" } }],
+    });
+
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).toContain("core, supporting, generic");
+  });
+
+  it("refuses a renderer where an extractor goes", () => {
+    const problems = check({
+      ...good,
+      extract: [{ ...good.extract[0], plugin: "markdown" }],
+    });
+
+    expect(problems.join("\n")).toContain("go-domain");
+  });
+
+  it("refuses a step that names no output", () => {
+    const { out, ...step } = good.extract[0];
+    const problems = check({ ...good, extract: [step] });
+
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).toContain('extract/0: "out" is missing');
+  });
+});
+
+describe("stepKeys", () => {
+  const step = (plugin, out, options) => ({ plugin, in: "svc", out, options });
+
+  it("keys a step by its plugin while it is the only one of that plugin in its directory", () => {
+    const go = step("go-domain", "svc/portolan", { out: "domain.json" });
+    const api = step("openapi", "svc/portolan", { out: "api.json" });
+    const keys = stepKeys({ extract: [go, api] });
+
+    expect(keys.keyOf(go)).toBe("go-domain");
+    expect(keys.keyOf(api)).toBe("openapi");
+    expect([...keys.liveIn("svc/portolan/")]).toEqual(["go-domain", "openapi"]);
+  });
+
+  it("tells two steps of one plugin in one directory apart by the file they name", () => {
+    const own = step("openapi", "svc/portolan", { out: "api.json" });
+    const vendored = step("openapi", "svc/portolan", { external: "psp", out: "psp.json" });
+    const elsewhere = step("openapi", "other/portolan", { out: "api.json" });
+    const keys = stepKeys({ extract: [own, vendored, elsewhere] });
+
+    expect(keys.keyOf(own)).toBe("openapi:api.json");
+    expect(keys.keyOf(vendored)).toBe("openapi:psp.json");
+    expect(keys.keyOf(elsewhere)).toBe("openapi");
+  });
+
+  it("refuses two steps that would write the same file", () => {
+    const manifest = {
+      generate: [step("markdown", "docs", { title: "A" }), step("markdown", "docs", { title: "B" })],
+    };
+    expect(() => stepKeys(manifest)).toThrow("nothing in their options tells them apart");
+
+    const same = {
+      extract: [step("openapi", "svc/portolan", { out: "api.json" }), step("openapi", "svc/portolan", { out: "api.json" })],
+    };
+    expect(() => stepKeys(same)).toThrow("two of them name api.json");
+  });
+});

package/scripts/output-path.mjs

@@ -0,0 +1,79 @@
+import {
+  closeSync,
+  constants,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
+
+/** Resolve one plugin-owned path and reject traversal and existing symlinks. */
+export function safeOutputPath(out, name) {
+  if (!name || isAbsolute(name) || /^[a-zA-Z]:/.test(name) || name.includes("\\")) {
+    throw new Error(`plugin asked to use ${JSON.stringify(name)}, which is not a relative path`);
+  }
+
+  const root = resolve(out);
+  const target = resolve(root, normalize(name));
+  const inside = relative(root, target);
+  if (inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside)) {
+    throw new Error(`plugin asked to use ${JSON.stringify(name)}, which is outside ${out}`);
+  }
+  assertNoSymlinks(root, inside, name);
+  return target;
+}
+
+/**
+ * Write after validating again immediately before open. The hook is used by a
+ * regression test to replace a checked directory with a symlink at the exact
+ * point where the historical implementation was vulnerable.
+ */
+export function writeOutputFile(out, name, contents, { beforeOpen } = {}) {
+  let target = safeOutputPath(out, name);
+  mkdirSync(dirname(target), { recursive: true });
+  beforeOpen?.({ target });
+
+  target = safeOutputPath(out, name);
+  assertParentInside(resolve(out), target, name);
+
+  const flags = constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC |
+    (constants.O_NOFOLLOW ?? 0);
+  const fd = openSync(target, flags, 0o644);
+  try {
+    writeFileSync(fd, contents, "utf8");
+  } finally {
+    closeSync(fd);
+  }
+}
+
+export function removeOutputFile(out, name) {
+  const target = safeOutputPath(out, name);
+  assertParentInside(resolve(out), target, name);
+  rmSync(target, { force: true });
+}
+
+function assertNoSymlinks(root, inside, name) {
+  let current = root;
+  for (const part of ["", ...inside.split(sep)]) {
+    if (part) current = join(current, part);
+    try {
+      if (lstatSync(current).isSymbolicLink()) {
+        throw new Error(`plugin asked to use ${JSON.stringify(name)}, but ${current} is a symlink`);
+      }
+    } catch (cause) {
+      if (cause?.code !== "ENOENT") throw cause;
+    }
+  }
+}
+
+function assertParentInside(root, target, name) {
+  const realRoot = realpathSync(root);
+  const realParent = realpathSync(dirname(target));
+  const held = relative(realRoot, realParent);
+  if (held === ".." || held.startsWith(`..${sep}`) || isAbsolute(held)) {
+    throw new Error(`plugin asked to use ${JSON.stringify(name)}, whose parent escaped ${root}`);
+  }
+}

package/scripts/output-path.test.mjs

@@ -0,0 +1,45 @@
+import { existsSync, mkdirSync, rmSync, symlinkSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { mkdtempSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+
+import { writeOutputFile } from "./output-path.mjs";
+
+describe("generated output paths", () => {
+  it("rejects a directory replaced by a symlink between validation and open", () => {
+    const root = mkdtempSync(join(tmpdir(), "portolan-output-"));
+    const out = join(root, "out");
+    const outside = join(root, "outside");
+    mkdirSync(join(out, "nested"), { recursive: true });
+    mkdirSync(outside);
+
+    try {
+      expect(() =>
+        writeOutputFile(out, "nested/result.json", "secret", {
+          beforeOpen: () => {
+            rmSync(join(out, "nested"), { recursive: true });
+            symlinkSync(outside, join(out, "nested"), "dir");
+          },
+        }),
+      ).toThrow("is a symlink");
+      expect(existsSync(join(outside, "result.json"))).toBe(false);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("refuses a symlink as the final output file", () => {
+    const root = mkdtempSync(join(tmpdir(), "portolan-output-"));
+    const out = join(root, "out");
+    const outside = join(root, "outside.txt");
+    mkdirSync(out);
+    symlinkSync(outside, join(out, "result.json"));
+    try {
+      expect(() => writeOutputFile(out, "result.json", "secret")).toThrow("is a symlink");
+      expect(existsSync(outside)).toBe(false);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/scripts/package-smoke.mjs

@@ -0,0 +1,37 @@
+// Exercises the CLI from a directory that contains none of Portolan's source.
+// This catches accidental cwd coupling before the same package reaches npm.
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const cli = resolve(root, "cli/portolan.mjs");
+const fixture = mkdtempSync(resolve(tmpdir(), "portolan-package-smoke-"));
+
+try {
+  writeFileSync(resolve(fixture, "package.json"), '{"name":"package-smoke","version":"1.0.0"}\n');
+  writeFileSync(resolve(fixture, "README.md"), "# Package smoke\n");
+  run("git", ["init", "--quiet"]);
+  run("git", ["config", "user.email", "portolan@example.invalid"]);
+  run("git", ["config", "user.name", "Portolan smoke test"]);
+  run(process.execPath, [cli, "init", "--cwd", fixture, "--yes"]);
+  run("git", ["add", "."]);
+  run("git", ["commit", "--quiet", "-m", "fixture"]);
+  run(process.execPath, [cli, "generate", "--cwd", fixture]);
+  run(process.execPath, [cli, "check", "--cwd", fixture]);
+  run(process.execPath, [cli, "build", "--cwd", fixture, "--output", "dist", "--base", "/architecture/"]);
+
+  for (const path of ["portolan/project.json", "docs/README.md", "dist/index.html", "dist/404.html"]) {
+    if (!existsSync(resolve(fixture, path))) throw new Error(`smoke test did not write ${path}`);
+  }
+  console.log("package smoke: init, generate, check, and build passed outside the repository");
+} finally {
+  rmSync(fixture, { recursive: true, force: true });
+}
+
+function run(command, args) {
+  execFileSync(command, args, { cwd: fixture, stdio: "inherit" });
+}