@paramour-js/next 0.1.0

package/dist/init/scaffold.js

@@ -0,0 +1,244 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { resolveRouteDirs } from "../scan.js";
+/**
+ * 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 function addPackageScript(text) {
+    const parsed = JSON.parse(text);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("package.json must contain an object");
+    }
+    const pkg = parsed;
+    if (pkg.scripts !== undefined &&
+        (typeof pkg.scripts !== "object" ||
+            pkg.scripts === null ||
+            Array.isArray(pkg.scripts))) {
+        // Spreading an array/string would silently rewrite it as index keys.
+        throw new Error(`"scripts" must be an object`);
+    }
+    const scripts = pkg.scripts;
+    if (scripts?.paramour !== undefined)
+        return { changed: false, text };
+    pkg.scripts = { ...scripts, paramour: "paramour generate" };
+    const indent = /^([ \t]+)"/m.exec(text)?.[1] ?? "  ";
+    const trailing = text.endsWith("\n") ? "\n" : "";
+    return { changed: true, text: JSON.stringify(pkg, null, indent) + trailing };
+}
+/**
+ * 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 function checkSetup(projectRoot, artifactPath) {
+    const checks = [];
+    try {
+        const dirs = resolveRouteDirs(projectRoot);
+        const found = [dirs.appDir, dirs.pagesDir]
+            .filter((dir) => dir !== undefined)
+            .map((dir) => `${relative(projectRoot, dir).replaceAll("\\", "/")}/`);
+        checks.push(found.length > 0
+            ? { label: `route directories: ${found.join(", ")}`, ok: true }
+            : {
+                detail: "create app/ or pages/, then run `paramour generate`",
+                label: "no route directory found yet",
+                ok: false,
+            });
+    }
+    catch (error) {
+        checks.push({
+            detail: error instanceof Error ? error.message : String(error),
+            label: "route-directory discovery failed",
+            ok: false,
+        });
+    }
+    checks.push(dependenciesCheck(projectRoot));
+    checks.push(tsconfigCheck(projectRoot, artifactPath));
+    return checks;
+}
+/** The starter `paramour.config.ts` — every field commented-out defaults. */
+export function paramourConfigTemplate() {
+    return [
+        `import type { ParamourConfig } from "@paramour-js/next";`,
+        "",
+        "/**",
+        " * Paramour CLI configuration. Every field is optional and every value",
+        " * below is the default — deleting this file changes nothing.",
+        " */",
+        "export default {",
+        `  // appDir: "app",`,
+        `  // outFile: "paramour-env.d.ts",`,
+        `  // pageExtensions: ["tsx", "ts", "jsx", "js"],`,
+        `  // pagesDir: "pages",`,
+        `  // routeFiles: ["src/routes/**/*.ts"], // pin \`paramour list\`'s definition scan`,
+        "} satisfies ParamourConfig;",
+        "",
+    ].join("\n");
+}
+/**
+ * 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 function stripJsonComments(text) {
+    let out = "";
+    let inString = false;
+    for (let i = 0; i < text.length; i++) {
+        // charAt, not indexing: "" past the end instead of undefined, so the
+        // lookahead needs no noUncheckedIndexedAccess dance.
+        const ch = text.charAt(i);
+        const next = text.charAt(i + 1);
+        if (inString) {
+            out += ch;
+            if (ch === "\\") {
+                out += next;
+                i++;
+                continue;
+            }
+            if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            out += ch;
+            continue;
+        }
+        if (ch === "/" && next === "/") {
+            while (i < text.length && text.charAt(i) !== "\n")
+                i++;
+            out += "\n";
+            continue;
+        }
+        if (ch === "/" && next === "*") {
+            i += 2;
+            while (i < text.length &&
+                !(text.charAt(i) === "*" && text.charAt(i + 1) === "/")) {
+                i++;
+            }
+            i++;
+            continue;
+        }
+        out += ch;
+    }
+    return stripTrailingCommas(out);
+}
+/** Exported for `doctor`, which reports the same heuristic as its own check. */
+export function tsconfigCheck(projectRoot, artifactPath) {
+    const tsconfigPath = join(projectRoot, "tsconfig.json");
+    const artifactRel = relative(projectRoot, artifactPath).replaceAll("\\", "/");
+    if (!existsSync(tsconfigPath)) {
+        return {
+            label: "no tsconfig.json — artifact-coverage check skipped",
+            ok: true,
+        };
+    }
+    let include;
+    try {
+        const parsed = JSON.parse(stripJsonComments(readFileSync(tsconfigPath, "utf8")));
+        include = parsed.include;
+    }
+    catch {
+        return {
+            detail: `could not parse it; make sure "${artifactRel}" is covered by \`include\``,
+            label: "tsconfig.json unreadable — artifact coverage unverified",
+            ok: false,
+        };
+    }
+    if (include === undefined) {
+        return {
+            label: `tsconfig.json covers ${artifactRel} (no include list)`,
+            ok: true,
+        };
+    }
+    if (Array.isArray(include) &&
+        include.some((pattern) => typeof pattern === "string" &&
+            tsconfigPatternCovers(pattern, artifactRel))) {
+        return { label: `tsconfig.json includes ${artifactRel}`, ok: true };
+    }
+    return {
+        detail: `add "${artifactRel}" to \`include\` so the registry augmentation loads`,
+        label: `tsconfig include may not cover ${artifactRel}`,
+        ok: false,
+    };
+}
+/**
+ * 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 function tsconfigPatternCovers(pattern, artifactRel) {
+    const normalized = pattern.replaceAll("\\", "/").replace(/^\.\//, "");
+    if (normalized === artifactRel)
+        return true;
+    if (!normalized.includes("*")) {
+        return artifactRel.startsWith(`${normalized.replace(/\/$/, "")}/`);
+    }
+    // The literal directory prefix before the first wildcard still restricts
+    // the match: `src/**/*.ts` cannot cover a root-level artifact.
+    const prefix = normalized
+        .slice(0, normalized.indexOf("*"))
+        .replace(/[^/]*$/, "");
+    return (artifactRel.startsWith(prefix) &&
+        normalized.includes("**") &&
+        (normalized.endsWith(".ts") || normalized.endsWith("*")));
+}
+function dependenciesCheck(projectRoot) {
+    let declared = {};
+    try {
+        const parsed = JSON.parse(readFileSync(join(projectRoot, "package.json"), "utf8"));
+        declared = { ...parsed.dependencies, ...parsed.devDependencies };
+    }
+    catch {
+        // Unreadable package.json is reported by init's own prerequisite check.
+    }
+    const missing = ["@paramour-js/next", "paramour"].filter((name) => declared[name] === undefined);
+    return missing.length === 0
+        ? { label: "dependencies declared: paramour, @paramour-js/next", ok: true }
+        : {
+            detail: "add them to package.json and install",
+            label: `missing dependencies: ${missing.join(", ")}`,
+            ok: false,
+        };
+}
+/**
+ * String-aware trailing-comma removal over comment-free JSONC — a flat
+ * regex would also rewrite `,}`/`,]` inside string literals (glob patterns).
+ */
+function stripTrailingCommas(text) {
+    let out = "";
+    let inString = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text.charAt(i);
+        if (inString) {
+            out += ch;
+            if (ch === "\\") {
+                out += text.charAt(i + 1);
+                i++;
+                continue;
+            }
+            if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            out += ch;
+            continue;
+        }
+        if (ch === ",") {
+            let j = i + 1;
+            while (j < text.length && /\s/.test(text.charAt(j)))
+                j++;
+            const sig = text.charAt(j);
+            if (sig === "}" || sig === "]")
+                continue;
+        }
+        out += ch;
+    }
+    return out;
+}

package/dist/init/wrap-next-config.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The `paramour init` next.config codemod (magicast: recast printing +
+ * babel-ts parsing, so TS/ESM configs transform format-preservingly).
+ * Anything the transform can't handle CONFIDENTLY degrades to a `manual`
+ * result carrying the exact snippet — init prints it and still exits 0; a
+ * printed instruction beats a mangled config.
+ */
+/** A next.config file found at the project root. */
+export interface FoundNextConfig {
+    lang: "js" | "mjs" | "ts";
+    path: string;
+}
+export type WrapResult = {
+    code: string;
+    status: "wrapped";
+} | {
+    snippet: string;
+    status: "manual";
+} | {
+    status: "already-wrapped";
+};
+/**
+ * Wrap-state probe for `doctor`: same import/callee detection the codemod
+ * uses for idempotence, without mutating anything.
+ */
+export declare function detectWrapState(source: string): Promise<"not-wrapped" | "unparseable" | "wrapped">;
+/** Probe order mirrors init's scaffolding preference: ts, mjs, js. */
+export declare function findNextConfig(projectRoot: string): FoundNextConfig | undefined;
+/** The `manual` fallback text — also printed when no config file exists. */
+export declare function manualSnippet(): string;
+/**
+ * The transform: add the named import (unless present under any alias) and
+ * rewrap the default export — identifier, object literal, existing wrapper
+ * call (`withBundleAnalyzer(...)` → wrapped outermost), or function/arrow
+ * form (withTypedRoutes accepts the config-function shape) all take the
+ * same path. Manual fallbacks: parse failure, no default export (includes
+ * CJS `module.exports` — this package is ESM-only, so a generated
+ * `require()` would be a trap), or any shape magicast refuses to rebuild.
+ * Idempotent: an already-wrapped export is detected, never double-wrapped.
+ */
+export declare function wrapNextConfigSource(source: string): Promise<WrapResult>;

package/dist/init/wrap-next-config.js

@@ -0,0 +1,99 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+const IMPORT_LINE = `import { withTypedRoutes } from "@paramour-js/next";`;
+/**
+ * Wrap-state probe for `doctor`: same import/callee detection the codemod
+ * uses for idempotence, without mutating anything.
+ */
+export async function detectWrapState(source) {
+    const { parseModule } = await import("magicast");
+    try {
+        const mod = parseModule(source);
+        const local = withTypedRoutesLocal(mod.imports.$items);
+        return isWrappedCall(mod.exports.default, local)
+            ? "wrapped"
+            : "not-wrapped";
+    }
+    catch {
+        return "unparseable";
+    }
+}
+/** Probe order mirrors init's scaffolding preference: ts, mjs, js. */
+export function findNextConfig(projectRoot) {
+    const probes = [
+        ["next.config.ts", "ts"],
+        ["next.config.mjs", "mjs"],
+        ["next.config.js", "js"],
+    ];
+    for (const [name, lang] of probes) {
+        const path = join(projectRoot, name);
+        if (existsSync(path))
+            return { lang, path };
+    }
+    return undefined;
+}
+/** The `manual` fallback text — also printed when no config file exists. */
+export function manualSnippet() {
+    return [
+        IMPORT_LINE,
+        "",
+        "// wrap your existing config export:",
+        "export default withTypedRoutes(nextConfig);",
+    ].join("\n");
+}
+/**
+ * The transform: add the named import (unless present under any alias) and
+ * rewrap the default export — identifier, object literal, existing wrapper
+ * call (`withBundleAnalyzer(...)` → wrapped outermost), or function/arrow
+ * form (withTypedRoutes accepts the config-function shape) all take the
+ * same path. Manual fallbacks: parse failure, no default export (includes
+ * CJS `module.exports` — this package is ESM-only, so a generated
+ * `require()` would be a trap), or any shape magicast refuses to rebuild.
+ * Idempotent: an already-wrapped export is detected, never double-wrapped.
+ */
+export async function wrapNextConfigSource(source) {
+    const { builders, generateCode, parseModule } = await import("magicast");
+    let mod;
+    try {
+        mod = parseModule(source);
+    }
+    catch {
+        return { snippet: manualSnippet(), status: "manual" };
+    }
+    try {
+        const local = withTypedRoutesLocal(mod.imports.$items);
+        const current = mod.exports.default;
+        if (current === undefined) {
+            return { snippet: manualSnippet(), status: "manual" };
+        }
+        if (isWrappedCall(current, local)) {
+            return { status: "already-wrapped" };
+        }
+        if (local === undefined) {
+            mod.imports.$prepend({
+                from: "@paramour-js/next",
+                imported: "withTypedRoutes",
+            });
+        }
+        mod.exports.default = builders.functionCall(local ?? "withTypedRoutes", current);
+        return { code: generateCode(mod).code, status: "wrapped" };
+    }
+    catch {
+        return { snippet: manualSnippet(), status: "manual" };
+    }
+}
+function isWrappedCall(value, local) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const node = value;
+    return (node.$type === "function-call" &&
+        typeof node.$callee === "string" &&
+        // Member-expression callees (`ptr.withTypedRoutes(...)`) count even
+        // without a named import — a namespace-wrapped config must not be
+        // double-wrapped (the prepended named import would be invalid ES).
+        ((local !== undefined && node.$callee === local) ||
+            node.$callee.endsWith(".withTypedRoutes")));
+}
+function withTypedRoutesLocal(items) {
+    return items.find((item) => item.from === "@paramour-js/next" && item.imported === "withTypedRoutes")?.local;
+}

package/dist/list/discover-route-defs.d.ts

@@ -0,0 +1,52 @@
+import type { AnyRoute, RouterKind } from "paramour";
+/**
+ * Route-definition discovery for `paramour list`/`doctor`: find the modules
+ * that call defineAppRoute/definePagesRoute, evaluate them, and collect the
+ * exported route objects. Generation never runs any of this — route shapes
+ * exist only on runtime route objects, so reading them means executing user
+ * modules; every failure degrades per-module rather than aborting the scan.
+ */
+export interface DiscoveryResult {
+    /** Deduped by `(router, path)`, in sorted-file order — first export wins. */
+    definitions: RouteDefinition[];
+    duplicates: DuplicateDefinition[];
+    /** Modules that matched the scan but threw when evaluated. */
+    loadFailures: LoadFailure[];
+}
+/** A later definition of a `(router, path)` already seen; first wins. */
+export interface DuplicateDefinition {
+    file: string;
+    firstFile: string;
+    path: string;
+    router: RouterKind;
+}
+export interface LoadFailure {
+    file: string;
+    message: string;
+}
+/** One discovered route object and where it came from. */
+export interface RouteDefinition {
+    exportName: string;
+    /** Project-root-relative, `/`-separated — stable across platforms. */
+    file: string;
+    route: AnyRoute;
+}
+/**
+ * Discovery = glob → content pre-filter → evaluate. The default glob is
+ * every source file outside the usual output dirs; a file is loaded only if
+ * its text mentions a define constructor (grep-then-load). `routeFiles`
+ * config globs replace the default patterns when the heuristic misfires.
+ *
+ * jiti evaluates matched files (the §7.2 loader carry-over). Known limits,
+ * both handled by the per-module degrade: tsconfig `paths` aliases are not
+ * resolved (a future improvement could feed them into jiti's `alias`
+ * option), and `server-only`-style imports throw outside Next.
+ */
+export declare function discoverRouteDefinitions(projectRoot: string, options?: {
+    routeFiles?: readonly string[] | undefined;
+}): Promise<DiscoveryResult>;
+/**
+ * The `(router, path)` identity key — discovery's dedupe, `list`'s
+ * definition overlay, and doctor's coverage count all build lookups with it.
+ */
+export declare function routeKey(router: RouterKind, path: string): string;

package/dist/list/discover-route-defs.js

@@ -0,0 +1,121 @@
+import { readFileSync, statSync } from "node:fs";
+import { relative } from "node:path";
+import { message } from "../cli-io.js";
+// No .jsx/.tsx: jiti does not transform JSX, so a matched component file
+// could never evaluate — it would only add load-failure noise (a page
+// merely MENTIONING defineAppRoute in prose already trips the content
+// pre-filter). Definitions living in JSX files need `routeFiles` globs.
+const DEFAULT_PATTERNS = ["**/*.{js,mjs,mts,ts}"];
+const IGNORE_PATTERNS = [
+    "**/.git/**",
+    "**/.next/**",
+    "**/build/**",
+    "**/coverage/**",
+    "**/dist/**",
+    "**/node_modules/**",
+    "**/out/**",
+];
+/** Files past this size skip the content pre-filter (bundles, lockfiles). */
+const MAX_PREFILTER_BYTES = 512 * 1024;
+/**
+ * Discovery = glob → content pre-filter → evaluate. The default glob is
+ * every source file outside the usual output dirs; a file is loaded only if
+ * its text mentions a define constructor (grep-then-load). `routeFiles`
+ * config globs replace the default patterns when the heuristic misfires.
+ *
+ * jiti evaluates matched files (the §7.2 loader carry-over). Known limits,
+ * both handled by the per-module degrade: tsconfig `paths` aliases are not
+ * resolved (a future improvement could feed them into jiti's `alias`
+ * option), and `server-only`-style imports throw outside Next.
+ */
+export async function discoverRouteDefinitions(projectRoot, options = {}) {
+    // Dynamic imports, same stance as config.ts: only commands that actually
+    // discover definitions pay for tinyglobby/jiti.
+    const { glob } = await import("tinyglobby");
+    const files = await glob(options.routeFiles === undefined
+        ? DEFAULT_PATTERNS
+        : [...options.routeFiles], { absolute: true, cwd: projectRoot, ignore: IGNORE_PATTERNS });
+    // Deterministic load order — dedupe's "first wins" must not depend on
+    // filesystem enumeration order.
+    files.sort();
+    const candidates = files.filter(mentionsDefineCall);
+    const { createJiti } = await import("jiti");
+    const jiti = createJiti(import.meta.url, {
+        fsCache: false,
+        interopDefault: true,
+    });
+    const definitions = [];
+    const duplicates = [];
+    const loadFailures = [];
+    const seen = new Map();
+    for (const file of candidates) {
+        const relFile = relative(projectRoot, file).replaceAll("\\", "/");
+        let mod;
+        try {
+            mod = await jiti.import(file);
+        }
+        catch (error) {
+            loadFailures.push({ file: relFile, message: message(error) });
+            continue;
+        }
+        if (typeof mod !== "object" || mod === null)
+            continue;
+        for (const [exportName, value] of Object.entries(mod)) {
+            if (!isRouteLike(value))
+                continue;
+            const key = routeKey(value["~router"], value.path);
+            const first = seen.get(key);
+            if (first !== undefined) {
+                duplicates.push({
+                    file: relFile,
+                    firstFile: first.file,
+                    path: value.path,
+                    router: value["~router"],
+                });
+                continue;
+            }
+            const definition = {
+                exportName,
+                file: relFile,
+                route: value,
+            };
+            seen.set(key, definition);
+            definitions.push(definition);
+        }
+    }
+    return { definitions, duplicates, loadFailures };
+}
+/**
+ * The `(router, path)` identity key — discovery's dedupe, `list`'s
+ * definition overlay, and doctor's coverage count all build lookups with it.
+ */
+export function routeKey(router, path) {
+    return `${router}\0${path}`;
+}
+/**
+ * Structural, not `instanceof` or brand-equality: the user's route objects
+ * come from THEIR `paramour` instance — a different module realm than the
+ * CLI's own dependency.
+ */
+function isRouteLike(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const route = value;
+    return (typeof route.path === "string" &&
+        (route["~router"] === "app" || route["~router"] === "pages") &&
+        typeof route["~params"] === "object" &&
+        route["~params"] !== null &&
+        Array.isArray(route["~segments"]));
+}
+function mentionsDefineCall(file) {
+    try {
+        const size = statSync(file, { throwIfNoEntry: false })?.size ?? 0;
+        if (size > MAX_PREFILTER_BYTES)
+            return false;
+        const text = readFileSync(file, "utf8");
+        return text.includes("defineAppRoute") || text.includes("definePagesRoute");
+    }
+    catch {
+        return false;
+    }
+}

package/dist/list/render.d.ts

@@ -0,0 +1,35 @@
+import type { CodecDescription, RouteDescription } from "paramour";
+import type { DuplicateDefinition, LoadFailure } from "./discover-route-defs.js";
+/** A discovered definition with its reflection attached. */
+export interface DescribedDefinition {
+    description: RouteDescription;
+    exportName: string;
+    file: string;
+}
+/** One filesystem route, with its definition overlay when one was found. */
+export interface ListedRoute {
+    definition: DescribedDefinition | null;
+    path: string;
+}
+/** Everything `paramour list` renders, human or `--json`. */
+export interface ListReport {
+    appRoutes: ListedRoute[];
+    duplicates: DuplicateDefinition[];
+    loadFailures: LoadFailure[];
+    /** Definitions whose `(router, path)` matched no filesystem route. */
+    orphans: DescribedDefinition[];
+    pagesRoutes: ListedRoute[];
+}
+/**
+ * `--json` payload. Keys are alphabetical; a route with no definition
+ * carries `definition: null` rather than an absent member — friendlier to
+ * both `jq` and exactOptionalPropertyTypes consumers.
+ */
+export declare function buildListJson(report: ListReport): unknown;
+/**
+ * `integer`, `enum(a, b)`, `string[]`, with annotations in fixed order:
+ * presence, default, catch.
+ */
+export declare function formatCodec(description: CodecDescription): string;
+/** Human report; one string per output line. */
+export declare function renderListReport(report: ListReport): string[];