@paramour-js/next 0.1.0

package/dist/doctor/checks.d.ts

@@ -0,0 +1,16 @@
+/**
+ * One `paramour doctor` finding. `fail` means a verification the user cares
+ * about is untrue (exit 1, same class as check-drift); `warn` is advisory
+ * and never affects the exit code.
+ */
+export interface DoctorCheck {
+    detail?: string[];
+    label: string;
+    status: "fail" | "pass" | "warn";
+}
+/**
+ * @internal The check battery, in report order. Each check degrades
+ * independently — doctor exists to diagnose broken setups, so a throwing
+ * probe becomes a finding, never a crash.
+ */
+export declare function runDoctorChecks(projectRoot: string): Promise<DoctorCheck[]>;

package/dist/doctor/checks.js

@@ -0,0 +1,231 @@
+import { readFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { resolveInputs } from "../cli-inputs.js";
+import { message } from "../cli-io.js";
+import { loadConfigFile } from "../config.js";
+import { checkArtifact, formatRouteDiff, } from "../generate.js";
+import { tsconfigCheck } from "../init/scaffold.js";
+import { detectWrapState, findNextConfig } from "../init/wrap-next-config.js";
+import { discoverRouteDefinitions, routeKey, } from "../list/discover-route-defs.js";
+import { scanRoutes } from "../scan.js";
+/**
+ * @internal The check battery, in report order. Each check degrades
+ * independently — doctor exists to diagnose broken setups, so a throwing
+ * probe becomes a finding, never a crash.
+ */
+export async function runDoctorChecks(projectRoot) {
+    const checks = [];
+    // 1. Config file parses and validates.
+    let config = {};
+    try {
+        const loaded = await loadConfigFile(projectRoot);
+        config = loaded?.config ?? {};
+        checks.push({
+            label: loaded === undefined
+                ? "config: no paramour.config file — defaults in effect"
+                : `config: ${basename(loaded.path)} is valid`,
+            status: "pass",
+        });
+    }
+    catch (error) {
+        checks.push({
+            detail: [message(error)],
+            label: "config: invalid",
+            status: "fail",
+        });
+    }
+    // 2. Route directories resolve (PR8 discovery, config dirs honored).
+    let inputs;
+    try {
+        inputs = await resolveInputs({}, projectRoot, config);
+        const dirs = [inputs.appDir, inputs.pagesDir]
+            .filter((dir) => dir !== undefined)
+            .map((dir) => `${relative(projectRoot, dir).replaceAll("\\", "/")}/`);
+        checks.push({
+            label: `route directories: ${dirs.join(", ")}`,
+            status: "pass",
+        });
+    }
+    catch (error) {
+        checks.push({
+            detail: [message(error)],
+            label: "route directories: not found",
+            status: "fail",
+        });
+    }
+    // 3. Artifact exists and is current (the `check` engine).
+    let routes;
+    if (inputs === undefined) {
+        checks.push({
+            label: "artifact: skipped (no route directories)",
+            status: "warn",
+        });
+    }
+    else {
+        const artifactRel = relative(projectRoot, inputs.artifactPath).replaceAll("\\", "/");
+        try {
+            routes = scanRoutes(inputs, inputs.pageExtensions);
+            const result = checkArtifact(inputs);
+            if (result.upToDate) {
+                checks.push({
+                    label: `artifact: ${artifactRel} is up to date`,
+                    status: "pass",
+                });
+            }
+            else {
+                checks.push({
+                    detail: [
+                        ...formatRouteDiff(result.app, result.pages),
+                        "run `paramour generate` and commit the result",
+                    ],
+                    label: result.missingFile
+                        ? `artifact: ${artifactRel} is missing`
+                        : `artifact: ${artifactRel} is out of date`,
+                    status: "fail",
+                });
+            }
+        }
+        catch (error) {
+            checks.push({
+                detail: [message(error)],
+                label: "artifact: check failed",
+                status: "fail",
+            });
+        }
+    }
+    // 4. next.config wraps withTypedRoutes — warn-level: CLI-only workflows
+    // (generate in a package script, check in CI) are legitimate.
+    const nextConfig = findNextConfig(projectRoot);
+    if (nextConfig === undefined) {
+        checks.push({
+            detail: ["`paramour init` can create and wrap one"],
+            label: "next.config: none found",
+            status: "warn",
+        });
+    }
+    else {
+        const name = basename(nextConfig.path);
+        try {
+            const state = await detectWrapState(readFileSync(nextConfig.path, "utf8"));
+            if (state === "wrapped") {
+                checks.push({
+                    label: `next.config: ${name} wraps withTypedRoutes`,
+                    status: "pass",
+                });
+            }
+            else {
+                checks.push({
+                    detail: [
+                        state === "unparseable"
+                            ? "could not parse it to verify"
+                            : "dev/build auto-regeneration is off; `paramour init` can wrap it (CLI-only workflows are fine)",
+                    ],
+                    label: `next.config: ${name} does not wrap withTypedRoutes`,
+                    status: "warn",
+                });
+            }
+        }
+        catch (error) {
+            checks.push({
+                detail: [message(error)],
+                label: `next.config: could not read ${name}`,
+                status: "warn",
+            });
+        }
+    }
+    // 5. Version alignment between the two packages.
+    checks.push(versionCheck(projectRoot));
+    // 6. tsconfig covers the artifact (init's warn-level heuristic).
+    // resolve, not join — an absolute outFile must win, as it does in
+    // resolveInputs.
+    const artifactPath = inputs?.artifactPath ??
+        resolve(projectRoot, config.outFile ?? "paramour-env.d.ts");
+    const coverage = tsconfigCheck(projectRoot, artifactPath);
+    checks.push({
+        ...(coverage.detail === undefined ? {} : { detail: [coverage.detail] }),
+        label: `tsconfig: ${coverage.label}`,
+        status: coverage.ok ? "pass" : "warn",
+    });
+    // 7. Route-definition discovery health (list's engine).
+    checks.push(await discoveryCheck(projectRoot, config, routes));
+    return checks;
+}
+async function discoveryCheck(projectRoot, config, routes) {
+    try {
+        const discovery = await discoverRouteDefinitions(projectRoot, {
+            routeFiles: config.routeFiles,
+        });
+        const files = new Set(discovery.definitions.map((definition) => definition.file));
+        const detail = [];
+        if (routes !== undefined) {
+            const defined = new Set(discovery.definitions.map((definition) => routeKey(definition.route["~router"], definition.route.path)));
+            const all = [
+                ...routes.appRoutes.map((path) => routeKey("app", path)),
+                ...routes.pagesRoutes.map((path) => routeKey("pages", path)),
+            ];
+            const covered = all.filter((key) => defined.has(key)).length;
+            detail.push(`${String(covered)} of ${String(all.length)} filesystem routes have definitions`);
+        }
+        for (const failure of discovery.loadFailures) {
+            detail.push(`failed to load ${failure.file}: ${failure.message}`);
+        }
+        for (const duplicate of discovery.duplicates) {
+            detail.push(`duplicate definition of ${duplicate.path} (${duplicate.router}) in ${duplicate.file} — ${duplicate.firstFile} wins`);
+        }
+        return {
+            detail,
+            label: `route definitions: ${String(discovery.definitions.length)} found in ${String(files.size)} module${files.size === 1 ? "" : "s"}`,
+            status: discovery.loadFailures.length > 0 || discovery.duplicates.length > 0
+                ? "warn"
+                : "pass",
+        };
+    }
+    catch (error) {
+        return {
+            detail: [message(error)],
+            label: "route definitions: discovery failed",
+            status: "warn",
+        };
+    }
+}
+function readVersion(projectRoot, name) {
+    // Walks upward like Node resolution: workspaces hoist dependencies to a
+    // parent node_modules, so a single project-root read hard-fails healthy
+    // monorepo setups.
+    for (let dir = projectRoot;; dir = dirname(dir)) {
+        try {
+            const parsed = JSON.parse(readFileSync(join(dir, "node_modules", ...name.split("/"), "package.json"), "utf8"));
+            return typeof parsed.version === "string" ? parsed.version : undefined;
+        }
+        catch {
+            if (dirname(dir) === dir)
+                return undefined;
+        }
+    }
+}
+function versionCheck(projectRoot) {
+    const core = readVersion(projectRoot, "paramour");
+    const next = readVersion(projectRoot, "@paramour-js/next");
+    const missing = [
+        ...(next === undefined ? ["@paramour-js/next"] : []),
+        ...(core === undefined ? ["paramour"] : []),
+    ];
+    if (missing.length > 0) {
+        return {
+            detail: ["install dependencies and re-run"],
+            label: `versions: ${missing.join(", ")} not resolvable in node_modules`,
+            status: "fail",
+        };
+    }
+    if (core !== next) {
+        return {
+            detail: ["align the two versions — they release in lockstep"],
+            label: `versions: paramour ${core ?? ""} != @paramour-js/next ${next ?? ""}`,
+            status: "warn",
+        };
+    }
+    return {
+        label: `versions: paramour and @paramour-js/next are both ${core ?? ""}`,
+        status: "pass",
+    };
+}

package/dist/emit.d.ts

@@ -0,0 +1,35 @@
+/** Result of {@link writeIfChanged}. */
+export interface WriteIfChangedResult {
+    /**
+     * Prior file content, or `null` when the file did not exist — the input
+     * for TR4's drift warning (which paths appeared/disappeared).
+     */
+    previousContent: null | string;
+    /**
+     * `false` on a byte-identical no-op — the signal `--check` (TR7) and the
+     * watch loop (TR5) hang off.
+     */
+    written: boolean;
+}
+/** Input of {@link emitArtifact} — one union per router (PR9). */
+export interface EmitRoutes {
+    appRoutes: readonly string[];
+    pagesRoutes: readonly string[];
+}
+/**
+ * Artifact text for the per-router route unions (TR3/PR9): deterministic —
+ * sorted, deduped, LF-only, trailing newline, no timestamps. Sorting/deduping
+ * happens here as well as in the scanner so byte-identity never depends on
+ * who the caller was. Always the leading-pipe multiline union form, even for
+ * one path — one shape, no count-dependent formatting. An empty union omits
+ * its member entirely (TR3's absent-not-`never` rule, applied per router in
+ * PR9): a pages-only project keeps world-A's permissive `string` fallback
+ * for `defineAppRoute`, and vice versa.
+ */
+export declare function emitArtifact(routes: EmitRoutes): string;
+/**
+ * Compare-before-write (TR3): a no-op regeneration must not touch the file —
+ * that property is what prevents TS-server churn, watch-loop feedback, and
+ * concurrent-generator races (TR6).
+ */
+export declare function writeIfChanged(filePath: string, content: string): WriteIfChangedResult;

package/dist/emit.js

@@ -0,0 +1,74 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+const HEADER = "// Generated by @paramour-js/next. Do not edit — regenerate with `paramour generate`.";
+/**
+ * Artifact text for the per-router route unions (TR3/PR9): deterministic —
+ * sorted, deduped, LF-only, trailing newline, no timestamps. Sorting/deduping
+ * happens here as well as in the scanner so byte-identity never depends on
+ * who the caller was. Always the leading-pipe multiline union form, even for
+ * one path — one shape, no count-dependent formatting. An empty union omits
+ * its member entirely (TR3's absent-not-`never` rule, applied per router in
+ * PR9): a pages-only project keeps world-A's permissive `string` fallback
+ * for `defineAppRoute`, and vice versa.
+ */
+export function emitArtifact(routes) {
+    const members = ["appRoutes", "pagesRoutes"].flatMap((member) => {
+        const sorted = [...new Set(routes[member])].sort();
+        if (sorted.length === 0)
+            return [];
+        // The union's closing `;` attaches to the last member line. Paths go
+        // through JSON.stringify, not raw `"${path}"`: a dirname may legally
+        // contain a quote or backslash (Linux/macOS), which unescaped would emit
+        // invalid TS or silently declare the wrong route. JSON string escaping is
+        // a subset of TS string-literal escaping (output stays valid TS) and is
+        // deterministic, so TR3's byte-identity guarantee holds.
+        return [
+            `    ${member}:`,
+            `${sorted.map((path) => `      | ${JSON.stringify(path)}`).join("\n")};`,
+        ];
+    });
+    if (members.length === 0) {
+        // TR3: no routes yet → NO members (explicitly not `never`, which would
+        // make every route-constructor call an error). The empty merge keeps
+        // the documented world-A `string` fallback (RL8).
+        return [
+            HEADER,
+            'import "paramour";',
+            "",
+            'declare module "paramour" {',
+            "  // TR3: empty merge — no routes discovered yet; the pre-generation",
+            "  // `string` fallback stays in effect.",
+            "  // eslint-disable-next-line @typescript-eslint/no-empty-object-type",
+            "  interface ParamourRegister {}",
+            "}",
+            "",
+        ].join("\n");
+    }
+    return [
+        HEADER,
+        'import "paramour";',
+        "",
+        'declare module "paramour" {',
+        "  interface ParamourRegister {",
+        ...members,
+        "  }",
+        "}",
+        "",
+    ].join("\n");
+}
+/**
+ * Compare-before-write (TR3): a no-op regeneration must not touch the file —
+ * that property is what prevents TS-server churn, watch-loop feedback, and
+ * concurrent-generator races (TR6).
+ */
+export function writeIfChanged(filePath, content) {
+    const previousContent = existsSync(filePath)
+        ? readFileSync(filePath, "utf8")
+        : null;
+    if (previousContent === content)
+        return { previousContent, written: false };
+    // TR3's outFile escape hatch may point into a not-yet-existing directory.
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, content);
+    return { previousContent, written: true };
+}

package/dist/generate.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The shared generation engine (TR9): `withTypedRoutes` and the CLI drive
+ * these same functions, so wrapper and `paramour generate` cannot drift on
+ * what a pass produces. Everything here is @internal — not barrel API.
+ */
+/** Result of {@link checkArtifact}. */
+export interface CheckResult {
+    /** App-router drift — split per router so the report names it (PR9). */
+    app: RouterDrift;
+    /** `true` when the artifact file does not exist at all. */
+    missingFile: boolean;
+    /** Pages-router drift. */
+    pages: RouterDrift;
+    /** `true` on a byte-identical artifact — the only non-drift state. */
+    upToDate: boolean;
+}
+/** Inputs to one generation/check pass; either dir may be absent (PR1). */
+export interface GenerateInputs {
+    appDir?: string | undefined;
+    artifactPath: string;
+    pageExtensions: readonly string[];
+    pagesDir?: string | undefined;
+}
+/** Result of {@link generate}. */
+export interface GenerateResult {
+    /** The freshly scanned app-route union (sorted). */
+    appRoutes: string[];
+    /** The freshly scanned pages-route union (sorted). */
+    pagesRoutes: string[];
+    /** Prior artifact content, `null` when the file did not exist. */
+    previousContent: null | string;
+    /** `false` on a byte-identical no-op (TR3 write-if-changed). */
+    written: boolean;
+}
+/** One router's appeared/disappeared route paths (TR4/TR7 drift). */
+export interface RouterDrift {
+    /** Routes on disk (scan) that the artifact lacks. */
+    appeared: string[];
+    /** Routes in the artifact that no longer exist on disk. */
+    disappeared: string[];
+}
+/**
+ * `--check` (TR7): scan to memory and byte-compare against disk — never
+ * writes. A missing artifact is drift, not an error: that is exactly the
+ * CI-degrades-to-world-A case the committed file exists to prevent (TR3).
+ */
+export declare function checkArtifact(inputs: GenerateInputs): CheckResult;
+/**
+ * Per-router drift of a completed {@link generate} pass against the artifact
+ * it replaced — the wrapper's build-phase drift report (TR4).
+ */
+export declare function diffGenerated(result: GenerateResult): {
+    app: RouterDrift;
+    pages: RouterDrift;
+};
+/**
+ * The `  + /new (app)` / `  - /old (pages)` lines of a drift report
+ * (TR4/TR7) — each line names the router its path moved in (PR9).
+ */
+export declare function formatRouteDiff(app: RouterDrift, pages: RouterDrift): string[];
+/** One generation pass: scan → emit → write-if-changed (TR3). */
+export declare function generate(inputs: GenerateInputs): GenerateResult;
+/**
+ * Per-router route paths in a previously emitted artifact; both empty for a
+ * missing file or the empty merge.
+ */
+export declare function parseArtifactRoutes(previousContent: null | string): {
+    appRoutes: Set<string>;
+    pagesRoutes: Set<string>;
+};

package/dist/generate.js

@@ -0,0 +1,106 @@
+import { existsSync, readFileSync } from "node:fs";
+import { emitArtifact, writeIfChanged } from "./emit.js";
+import { scanRoutes } from "./scan.js";
+/**
+ * Reads the per-router unions back out of a previously emitted artifact for
+ * drift diffs (TR4/TR7). Only ever applied to text this package generated
+ * (TR3 deterministic form), so line-anchored matches on the member headers
+ * and union members are exact, not heuristic. `\s*$` on both tolerates a
+ * CRLF-resaved artifact.
+ */
+const MEMBER_HEADER = /^\s*(appRoutes|pagesRoutes):\s*$/;
+const UNION_MEMBER = /^\s*\| "(.*)";?\s*$/;
+/**
+ * `--check` (TR7): scan to memory and byte-compare against disk — never
+ * writes. A missing artifact is drift, not an error: that is exactly the
+ * CI-degrades-to-world-A case the committed file exists to prevent (TR3).
+ */
+export function checkArtifact(inputs) {
+    const routes = scanRoutes(inputs, inputs.pageExtensions);
+    const expected = emitArtifact(routes);
+    const current = existsSync(inputs.artifactPath)
+        ? readFileSync(inputs.artifactPath, "utf8")
+        : null;
+    if (current === expected) {
+        return {
+            app: { appeared: [], disappeared: [] },
+            missingFile: false,
+            pages: { appeared: [], disappeared: [] },
+            upToDate: true,
+        };
+    }
+    const previous = parseArtifactRoutes(current);
+    return {
+        app: diffRouter(routes.appRoutes, previous.appRoutes),
+        missingFile: current === null,
+        pages: diffRouter(routes.pagesRoutes, previous.pagesRoutes),
+        upToDate: false,
+    };
+}
+/**
+ * Per-router drift of a completed {@link generate} pass against the artifact
+ * it replaced — the wrapper's build-phase drift report (TR4).
+ */
+export function diffGenerated(result) {
+    const previous = parseArtifactRoutes(result.previousContent);
+    return {
+        app: diffRouter(result.appRoutes, previous.appRoutes),
+        pages: diffRouter(result.pagesRoutes, previous.pagesRoutes),
+    };
+}
+/**
+ * The `  + /new (app)` / `  - /old (pages)` lines of a drift report
+ * (TR4/TR7) — each line names the router its path moved in (PR9).
+ */
+export function formatRouteDiff(app, pages) {
+    return [
+        ...app.appeared.map((path) => `  + ${path} (app)`),
+        ...pages.appeared.map((path) => `  + ${path} (pages)`),
+        ...app.disappeared.map((path) => `  - ${path} (app)`),
+        ...pages.disappeared.map((path) => `  - ${path} (pages)`),
+    ];
+}
+/** One generation pass: scan → emit → write-if-changed (TR3). */
+export function generate(inputs) {
+    const routes = scanRoutes(inputs, inputs.pageExtensions);
+    return {
+        ...routes,
+        ...writeIfChanged(inputs.artifactPath, emitArtifact(routes)),
+    };
+}
+/**
+ * Per-router route paths in a previously emitted artifact; both empty for a
+ * missing file or the empty merge.
+ */
+export function parseArtifactRoutes(previousContent) {
+    const appRoutes = new Set();
+    const pagesRoutes = new Set();
+    if (previousContent === null)
+        return { appRoutes, pagesRoutes };
+    let current;
+    for (const line of previousContent.split("\n")) {
+        const header = MEMBER_HEADER.exec(line);
+        if (header !== null) {
+            current = header[1] === "appRoutes" ? appRoutes : pagesRoutes;
+            continue;
+        }
+        const member = UNION_MEMBER.exec(line);
+        if (member !== null) {
+            const [, path] = member;
+            if (path !== undefined)
+                current?.add(path);
+            continue;
+        }
+        // Any other line ends the member block — union members are contiguous
+        // in the TR3 deterministic form.
+        current = undefined;
+    }
+    return { appRoutes, pagesRoutes };
+}
+function diffRouter(fresh, previous) {
+    const freshSet = new Set(fresh);
+    return {
+        appeared: fresh.filter((path) => !previous.has(path)),
+        disappeared: [...previous].filter((path) => !freshSet.has(path)),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { RouteCollisionError } from "./collisions.js";
+export { type ParamourConfig } from "./config.js";
+export { emitArtifact, type EmitRoutes, writeIfChanged, type WriteIfChangedResult, } from "./emit.js";
+export { type AcquireLockResult, acquireWatcherLock } from "./lock.js";
+export { DEFAULT_PAGE_EXTENSIONS, scanAppRoutes } from "./scan-app.js";
+export { scanPagesRoutes } from "./scan-pages.js";
+export { resolveRouteDirs, type RouteDirs, scanRoutes, type ScanRoutesResult, } from "./scan.js";
+export { DEFAULT_DEBOUNCE_MS, type RouteDirsWatcher, watchRouteDirs, type WatchRouteDirsOptions, } from "./watch.js";
+export { withTypedRoutes, type WithTypedRoutesOptions, } from "./with-typed-routes.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+export { RouteCollisionError } from "./collisions.js";
+export {} from "./config.js";
+export { emitArtifact, writeIfChanged, } from "./emit.js";
+export { acquireWatcherLock } from "./lock.js";
+export { DEFAULT_PAGE_EXTENSIONS, scanAppRoutes } from "./scan-app.js";
+export { scanPagesRoutes } from "./scan-pages.js";
+export { resolveRouteDirs, scanRoutes, } from "./scan.js";
+export { DEFAULT_DEBOUNCE_MS, watchRouteDirs, } from "./watch.js";
+export { withTypedRoutes, } from "./with-typed-routes.js";

package/dist/init/scaffold.d.ts

@@ -0,0 +1,39 @@
+/** One line of init's detect-and-verify summary; `ok: false` renders ⚠. */
+export interface SetupCheck {
+    detail?: string;
+    label: string;
+    ok: boolean;
+}
+/**
+ * Insert `"paramour": "paramour generate"` into a package.json's scripts,
+ * preserving the file's own indentation and trailing-newline choice.
+ * Throws on malformed JSON — a broken package.json is init's one hard
+ * prerequisite failure.
+ */
+export declare function addPackageScript(text: string): {
+    changed: boolean;
+    text: string;
+};
+/**
+ * The detect-and-verify summary: route dirs discoverable, both packages
+ * declared, tsconfig covering the artifact. Warn-level throughout — a fresh
+ * project legitimately fails several of these, so none affect init's exit
+ * code.
+ */
+export declare function checkSetup(projectRoot: string, artifactPath: string): SetupCheck[];
+/** The starter `paramour.config.ts` — every field commented-out defaults. */
+export declare function paramourConfigTemplate(): string;
+/**
+ * Tolerant-enough JSONC → JSON for tsconfig reads: strips line and block
+ * comments outside strings, then trailing commas. Heuristic by design — the
+ * one consumer is a warn-level check.
+ */
+export declare function stripJsonComments(text: string): string;
+/** Exported for `doctor`, which reports the same heuristic as its own check. */
+export declare function tsconfigCheck(projectRoot: string, artifactPath: string): SetupCheck;
+/**
+ * Does a tsconfig `include` pattern cover the artifact? NOT a glob engine:
+ * exact match, directory prefix, or a `**` pattern whose extension can
+ * match a `.d.ts` (Next's default globstar-`.ts` include is the target case).
+ */
+export declare function tsconfigPatternCovers(pattern: string, artifactRel: string): boolean;