@codefast/cli 0.11.0 → 0.13.0

package/dist/audit/publish/run.js

@@ -0,0 +1,91 @@
+import path from "node:path";
+import { scanLegacySubpathImports } from "#audit/publish/domain/legacy-subpath";
+import { missesShippedFiles, scanStylesheetSources } from "#audit/publish/domain/stylesheet-sources";
+import { listShippedFiles } from "#audit/publish/shipped-files";
+import { AppError, messageFrom } from "#core/errors";
+import { err, ok } from "#core/result";
+import { listWorkspacePackageDirectories } from "#core/workspace/resolver";
+import { sourceCommentLanguage, walkSourceFiles } from "#core/workspace/source-walk";
+import { packageJsonFileName } from "#core/workspace/well-known-files";
+import { unshippedPublishTargets } from "#pack-slim/domain/transform";
+/**
+ * Reports what would break a consumer's install: a `#/`-prefixed import Node's ESM resolver rejects on
+ * the floor, an `exports`/`imports` target the slimmed publish manifest does not ship, and a shipped
+ * stylesheet whose `@source` paths reach none of the files that do ship.
+ *
+ * @since 0.12.0
+ */
+export async function runPublishAudit(fs, args) {
+    try {
+        const { rootDir, targetPath } = args;
+        const legacyImportFiles = [];
+        let legacyImportCount = 0;
+        // Tests are not published and may hold `#/` fixtures on purpose, so the specifier scan skips them.
+        const sourceFiles = walkSourceFiles(targetPath, fs).filter((filePath) => sourceCommentLanguage(filePath) === "js" && !filePath.split(path.sep).includes("tests"));
+        for (const absolutePath of sourceFiles) {
+            const imports = scanLegacySubpathImports(fs.readFileSync(absolutePath, "utf8"));
+            if (imports.length === 0) {
+                continue;
+            }
+            legacyImportCount += imports.length;
+            legacyImportFiles.push({ relativePath: toPosixPath(path.relative(rootDir, absolutePath)), imports });
+        }
+        const layout = await listWorkspacePackageDirectories(rootDir, fs, true);
+        const unshipped = [];
+        const unreachableStylesheets = [];
+        let packageCount = 0;
+        for (const packageDir of layout.packageDirectoryPathsAbsolute) {
+            const manifestPath = path.join(packageDir, packageJsonFileName);
+            if (!fs.existsSync(manifestPath)) {
+                continue;
+            }
+            const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+            if (manifest.private === true) {
+                continue;
+            }
+            packageCount++;
+            const packageName = typeof manifest.name === "string" ? manifest.name : toPosixPath(path.relative(rootDir, packageDir));
+            for (const target of unshippedPublishTargets(manifest)) {
+                unshipped.push({ packageName, field: target.field, subpath: target.subpath, target: target.target });
+            }
+            for (const violation of unreachableStylesheetsOf(fs, { rootDir, packageDir, manifest })) {
+                unreachableStylesheets.push({ packageName, ...violation });
+            }
+        }
+        return ok({
+            legacyImportFiles,
+            unshipped,
+            unreachableStylesheets,
+            legacyImportCount,
+            scannedFileCount: sourceFiles.length,
+            packageCount,
+        });
+    }
+    catch (caughtError) {
+        return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));
+    }
+}
+// The shipped stylesheets whose `@source` paths register nothing the tarball ships — what a consumer's Tailwind scans.
+function unreachableStylesheetsOf(fs, args) {
+    const { rootDir, packageDir, manifest } = args;
+    const shipped = listShippedFiles(fs, packageDir, manifest);
+    if (shipped === null) {
+        return [];
+    }
+    const violations = [];
+    for (const stylesheet of shipped.files.filter((file) => file.endsWith(".css"))) {
+        const stylesheetPath = path.join(packageDir, stylesheet);
+        const sources = scanStylesheetSources(fs.readFileSync(stylesheetPath, "utf8"));
+        if (sources.length > 0 && missesShippedFiles(stylesheet, sources, shipped.files)) {
+            violations.push({
+                stylesheet: toPosixPath(path.relative(rootDir, stylesheetPath)),
+                sources,
+                missingFilesEntries: shipped.missingEntries,
+            });
+        }
+    }
+    return violations;
+}
+function toPosixPath(filePath) {
+    return filePath.split(path.sep).join("/");
+}

package/dist/audit/publish/shipped-files.d.ts

@@ -0,0 +1,21 @@
+/** Lists the files a package's slimmed tarball ships, read from disk. */
+import type { Filesystem } from "#core/filesystem/filesystem";
+/**
+ * What a package's tarball ships, plus the `files` entries that match nothing on disk.
+ *
+ * @since 0.13.0
+ */
+export interface ShippedFiles {
+    /** Package-relative POSIX paths, sorted. */
+    readonly files: Array<string>;
+    readonly missingEntries: Array<string>;
+}
+/**
+ * Lists the files a package ships once the publish step has slimmed it, or `null` with no `files` field to go by.
+ *
+ * @remarks Applies the same slim as `pack-slim`, so a subtree it drops is absent here too, and leaves out source maps,
+ * which the publish step deletes. Without a `files` field npm ships the whole directory, which leaves nothing to judge.
+ *
+ * @since 0.13.0
+ */
+export declare function listShippedFiles(fs: Filesystem, packageDir: string, manifest: Record<string, unknown>): ShippedFiles | null;

package/dist/audit/publish/shipped-files.js

@@ -0,0 +1,36 @@
+/** Lists the files a package's slimmed tarball ships, read from disk. */
+import path from "node:path";
+import { isSourceMapFile, slimPublishManifest } from "#pack-slim/domain/transform";
+/**
+ * Lists the files a package ships once the publish step has slimmed it, or `null` with no `files` field to go by.
+ *
+ * @remarks Applies the same slim as `pack-slim`, so a subtree it drops is absent here too, and leaves out source maps,
+ * which the publish step deletes. Without a `files` field npm ships the whole directory, which leaves nothing to judge.
+ *
+ * @since 0.13.0
+ */
+export function listShippedFiles(fs, packageDir, manifest) {
+    const { manifest: slimmed } = slimPublishManifest(manifest);
+    if (!Array.isArray(slimmed.files)) {
+        return null;
+    }
+    const files = new Set();
+    const missingEntries = [];
+    for (const entry of slimmed.files) {
+        if (typeof entry !== "string" || entry.startsWith("!")) {
+            continue;
+        }
+        // An entry names a file, a directory whose whole subtree ships, or a glob.
+        const matches = [...fs.globSync(entry, { cwd: packageDir }), ...fs.globSync(`${entry}/**`, { cwd: packageDir })];
+        if (matches.length === 0) {
+            missingEntries.push(entry);
+            continue;
+        }
+        for (const match of matches) {
+            if (fs.statSync(path.join(packageDir, match)).isFile()) {
+                files.add(match.split(path.sep).join("/"));
+            }
+        }
+    }
+    return { files: [...files].filter((file) => !isSourceMapFile(file)).sort(), missingEntries };
+}

package/dist/audit/rtl/cli-result.d.ts

@@ -1,4 +1,4 @@
-import type { RtlAuditResult } from "#/audit/domain/types";
+import type { RtlAuditResult } from "#audit/domain/types";
 /**
  * Exit `1` when any non-allowlisted violation remains.
  *

package/dist/audit/rtl/cli-result.js

@@ -1,4 +1,4 @@
-import { CLI_EXIT_GENERAL_ERROR, CLI_EXIT_SUCCESS } from "#/core/exit-codes";
+import { CLI_EXIT_GENERAL_ERROR, CLI_EXIT_SUCCESS } from "#core/exit-codes";
 /**
  * Exit `1` when any non-allowlisted violation remains.
  *

package/dist/audit/rtl/domain/audit-file.d.ts

@@ -1,4 +1,4 @@
-import type { RtlViolation } from "#/audit/domain/types";
+import type { RtlViolation } from "#audit/domain/types";
 /**
  * Detects physical-direction Tailwind classes that should be logical or rtl:-paired.
  *

package/dist/audit/rtl/domain/audit-file.js

@@ -1,5 +1,5 @@
-import { DIRECTION_RESOLVED_VARIANT, PHYSICAL_SIDE_VARIANT, RTL_MAPPINGS, RTL_REVERSE_MAPPINGS, RTL_SWAP_MAPPINGS, RTL_TRANSLATE_X_MAPPINGS, SLIDE_PREFIXES, } from "#/audit/rtl/domain/mappings";
-import { collectTokens } from "#/audit/rtl/domain/tokenize";
+import { DIRECTION_RESOLVED_VARIANT, PHYSICAL_SIDE_VARIANT, RTL_MAPPINGS, RTL_REVERSE_MAPPINGS, RTL_SWAP_MAPPINGS, RTL_TRANSLATE_X_MAPPINGS, SLIDE_PREFIXES, } from "#audit/rtl/domain/mappings";
+import { collectTokens } from "#audit/rtl/domain/tokenize";
 /**
  * A token satisfies an "rtl companion" requirement when the same file has a
  * token whose variants include `rtl` and whose value matches. Variant order

package/dist/audit/rtl/domain/tokenize.d.ts

@@ -1,4 +1,4 @@
-import type { RtlClassToken } from "#/audit/domain/types";
+import type { RtlClassToken } from "#audit/domain/types";
 /**
  * Splits a class token into [variant, value, modifier], colon/slash-aware of
  * brackets and parens (arbitrary values like data-[side=left] or calc(...)).

package/dist/audit/rtl/output.d.ts

@@ -1,4 +1,4 @@
-import type { RtlAuditResult } from "#/audit/domain/types";
+import type { RtlAuditResult } from "#audit/domain/types";
 /**
  * Human-readable RTL audit report (matches the former packages/ui script shape).
  *

package/dist/audit/rtl/output.js

@@ -1,4 +1,4 @@
-import { logger } from "#/core/logger";
+import { logger } from "#core/logger";
 /**
  * Human-readable RTL audit report (matches the former packages/ui script shape).
  *

package/dist/audit/rtl/prepare.d.ts

@@ -1,7 +1,7 @@
-import type { AuditCommandPrelude } from "#/audit/prepare";
-import { AppError } from "#/core/errors";
-import type { Filesystem } from "#/core/filesystem/filesystem";
-import type { Result } from "#/core/result";
+import type { AuditCommandPrelude } from "#audit/prepare";
+import { AppError } from "#core/errors";
+import type { Filesystem } from "#core/filesystem/filesystem";
+import type { Result } from "#core/result";
 /**
  * Loads config and resolves the scan target for `audit rtl`.
  *

package/dist/audit/rtl/prepare.js

@@ -1,8 +1,8 @@
-import { resolveRepoRelativePath } from "#/audit/prepare";
-import { loadCodefastConfig } from "#/core/config";
-import { AppError, messageFrom } from "#/core/errors";
-import { err, ok } from "#/core/result";
-import { resolveProjectRoot } from "#/core/workspace/resolver";
+import { resolveRepoRelativePath } from "#audit/prepare";
+import { loadCodefastConfig } from "#core/config";
+import { AppError, messageFrom } from "#core/errors";
+import { err, ok } from "#core/result";
+import { resolveProjectRoot } from "#core/workspace/resolver";
 /**
  * Loads config and resolves the scan target for `audit rtl`.
  *

package/dist/audit/rtl/run.d.ts

@@ -1,7 +1,7 @@
-import type { RtlAuditResult } from "#/audit/domain/types";
-import { AppError } from "#/core/errors";
-import type { Filesystem } from "#/core/filesystem/filesystem";
-import type { Result } from "#/core/result";
+import type { RtlAuditResult } from "#audit/domain/types";
+import { AppError } from "#core/errors";
+import type { Filesystem } from "#core/filesystem/filesystem";
+import type { Result } from "#core/result";
 /**
  * Scans a target path for physical-direction Tailwind class violations.
  *

package/dist/audit/rtl/run.js

@@ -1,8 +1,8 @@
 import path from "node:path";
-import { auditFileContent } from "#/audit/rtl/domain/audit-file";
-import { AppError, messageFrom } from "#/core/errors";
-import { err, ok } from "#/core/result";
-import { walkTsxFiles } from "#/core/workspace/typescript-walk";
+import { auditFileContent } from "#audit/rtl/domain/audit-file";
+import { AppError, messageFrom } from "#core/errors";
+import { err, ok } from "#core/result";
+import { walkTsxFiles } from "#core/workspace/typescript-walk";
 /**
  * Scans a target path for physical-direction Tailwind class violations.
  *

package/dist/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
 import process from "node:process";
-import { runCli } from "#/cli";
+import { runCli } from "#cli";
 const code = await runCli(process.argv);
 process.exit(code);

package/dist/cli.js

@@ -3,11 +3,11 @@ import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
-import { createArrangeCommand } from "#/arrange/command";
-import { createAuditCommand } from "#/audit/command";
-import { createMirrorCommand } from "#/mirror/command";
-import { createPackSlimCommand } from "#/pack-slim/command";
-import { createTagCommand } from "#/tag/command";
+import { createArrangeCommand } from "#arrange/command";
+import { createAuditCommand } from "#audit/command";
+import { createMirrorCommand } from "#mirror/command";
+import { createPackSlimCommand } from "#pack-slim/command";
+import { createTagCommand } from "#tag/command";
 function readVersion() {
     try {
         const dir = path.dirname(fileURLToPath(import.meta.url));

package/dist/core/cli/command-pipeline.d.ts

@@ -1,9 +1,9 @@
 import type { Command } from "commander";
 import type { ZodType } from "zod";
-import type { GlobalCliOptions } from "#/core/cli/global-options";
-import type { AppError } from "#/core/errors";
-import type { Filesystem } from "#/core/filesystem/filesystem";
-import type { Result } from "#/core/result";
+import type { GlobalCliOptions } from "#core/cli/global-options";
+import type { AppError } from "#core/errors";
+import type { Filesystem } from "#core/filesystem/filesystem";
+import type { Result } from "#core/result";
 /**
  * The options every command shares: the `--json` machine-output flag. Per-command option shapes extend this.
  *
@@ -52,7 +52,6 @@ export interface CommandPipeline<Prelude, Request, RunResult, Presenter = never,
         readonly name: string;
         readonly help: string;
     } | undefined;
-    readonly jsonHelp?: string | undefined;
     readonly configureArgv?: ((command: Command) => void) | undefined;
     readonly prepare: CommandPrepare<Prelude>;
     readonly guard?: ((input: {

package/dist/core/cli/command-pipeline.js

@@ -1,10 +1,10 @@
 import process from "node:process";
-import { globalCliCommanderOptionsSchema } from "#/core/cli/global-options";
-import { readOptionalPositionalArg } from "#/core/cli/positional";
-import { consumeCliAppError } from "#/core/cli/result-handle";
-import { logger } from "#/core/logger";
-import { parseWithSchema } from "#/core/schema-parse";
-const DEFAULT_JSON_HELP = "Print one JSON summary on stdout (suppresses human progress)";
+import { globalCliCommanderOptionsSchema } from "#core/cli/global-options";
+import { readOptionalPositionalArg } from "#core/cli/positional";
+import { consumeCliAppError } from "#core/cli/result-handle";
+import { logger } from "#core/logger";
+import { parseWithSchema } from "#core/schema-parse";
+const DEFAULT_JSON_HELP = "Print one JSON object on stdout instead of the human-readable output";
 function readGlobalOptions(command) {
     return (command.optsWithGlobals?.() ?? command.opts());
 }
@@ -68,7 +68,7 @@ export function applyCommandPipeline(command, fs, pipeline) {
     if (pipeline.positional) {
         command.argument(pipeline.positional.name, pipeline.positional.help);
     }
-    command.option("--json", pipeline.jsonHelp ?? DEFAULT_JSON_HELP, false);
+    command.option("--json", DEFAULT_JSON_HELP, false);
     pipeline.configureArgv?.(command);
     command.action(makeAction(fs, pipeline));
     return command;

package/dist/core/cli/format-error.d.ts

@@ -1,4 +1,4 @@
-import type { AppError } from "#/core/errors";
+import type { AppError } from "#core/errors";
 /**
  * Formats an `AppError` as a `[CODE] message` line for CLI output.
  *

package/dist/core/cli/resolve-root.d.ts

@@ -1,6 +1,6 @@
-import { AppError } from "#/core/errors";
-import type { Filesystem } from "#/core/filesystem/filesystem";
-import type { Result } from "#/core/result";
+import { AppError } from "#core/errors";
+import type { Filesystem } from "#core/filesystem/filesystem";
+import type { Result } from "#core/result";
 /**
  * Resolves the project root as a `Result`, mapping a resolution failure to an `INFRA_FAILURE` error.
  *

package/dist/core/cli/resolve-root.js

@@ -1,6 +1,6 @@
-import { AppError, messageFrom } from "#/core/errors";
-import { err, ok } from "#/core/result";
-import { resolveProjectRoot } from "#/core/workspace/resolver";
+import { AppError, messageFrom } from "#core/errors";
+import { err, ok } from "#core/result";
+import { resolveProjectRoot } from "#core/workspace/resolver";
 /**
  * Resolves the project root as a `Result`, mapping a resolution failure to an `INFRA_FAILURE` error.
  *

package/dist/core/cli/result-handle.d.ts

@@ -1,5 +1,5 @@
-import type { AppError } from "#/core/errors";
-import type { Result } from "#/core/result";
+import type { AppError } from "#core/errors";
+import type { Result } from "#core/result";
 /**
  * Narrows a `Result`, reporting a failure and setting the exit code, or logging an optional success message.
  *

package/dist/core/cli/result-handle.js

@@ -1,8 +1,8 @@
 import process from "node:process";
-import { formatAppError } from "#/core/cli/format-error";
-import { CLI_EXIT_GENERAL_ERROR, CLI_EXIT_USAGE } from "#/core/exit-codes";
-import { logger } from "#/core/logger";
-import { isVerboseCliDiagnostics } from "#/core/verbose-diagnostics";
+import { formatAppError } from "#core/cli/format-error";
+import { CLI_EXIT_GENERAL_ERROR, CLI_EXIT_USAGE } from "#core/exit-codes";
+import { logger } from "#core/logger";
+import { isVerboseCliDiagnostics } from "#core/verbose-diagnostics";
 function exitCodeForAppError(error) {
     switch (error.code) {
         case "NOT_FOUND":

package/dist/core/config/define-config.d.ts

@@ -1,4 +1,4 @@
-import type { CodefastConfig } from "#/core/config/schema";
+import type { CodefastConfig } from "#core/config/schema";
 /**
  * Types a `codefast.config.*` object for editor autocomplete and type-checking; returns it unchanged.
  *

package/dist/core/config/loader.d.ts

@@ -1,5 +1,5 @@
-import type { CodefastConfig } from "#/core/config/schema";
-import type { Filesystem } from "#/core/filesystem/filesystem";
+import type { CodefastConfig } from "#core/config/schema";
+import type { Filesystem } from "#core/filesystem/filesystem";
 /**
  * A loaded config together with its schema warnings and the path it was read from.
  *

package/dist/core/config/loader.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import jiti from "jiti";
-import { codefastConfigRootSchema } from "#/core/config/schema";
-import { ancestorDirectories } from "#/core/workspace/ancestor-directories";
+import { codefastConfigRootSchema } from "#core/config/schema";
+import { ancestorDirectories } from "#core/workspace/ancestor-directories";
 function formatZodError(error, filePath) {
     const formatted = error.issues
         .map((issue) => {

package/dist/core/config/schema.d.ts

@@ -71,7 +71,12 @@ interface CodefastAuditConfig {
     links?: CodefastAuditAllowlistConfig | undefined;
     comments?: CodefastAuditAllowlistConfig | undefined;
     imports?: CodefastAuditAllowlistConfig | undefined;
+    assertions?: CodefastAuditAllowlistConfig | undefined;
     displayNames?: CodefastAuditAllowlistConfig | undefined;
+    constants?: {
+        target?: string | undefined;
+        allowlist?: Array<string> | undefined;
+    } | undefined;
 }
 /**
  * The validated root `codefast.config` shape.

package/dist/core/config/schema.js

@@ -58,7 +58,9 @@ const codefastAuditConfigSchema = z
     links: codefastAuditAllowlistConfigSchema.optional(),
     comments: codefastAuditAllowlistConfigSchema.optional(),
     imports: codefastAuditAllowlistConfigSchema.optional(),
+    assertions: codefastAuditAllowlistConfigSchema.optional(),
     displayNames: codefastAuditAllowlistConfigSchema.optional(),
+    constants: codefastAuditRtlConfigSchema.optional(),
 })
     .strict();
 /**

package/dist/core/config/warnings.js

@@ -1,4 +1,4 @@
-import { logger } from "#/core/logger";
+import { logger } from "#core/logger";
 const yellowAnsi = "\x1b[33m";
 const resetAnsi = "\x1b[0m";
 /**

package/dist/core/config.d.ts

@@ -1,7 +1,7 @@
-import type { CodefastConfig } from "#/core/config/schema";
-import { AppError } from "#/core/errors";
-import type { Filesystem } from "#/core/filesystem/filesystem";
-import type { Result } from "#/core/result";
+import type { CodefastConfig } from "#core/config/schema";
+import { AppError } from "#core/errors";
+import type { Filesystem } from "#core/filesystem/filesystem";
+import type { Result } from "#core/result";
 /**
  * Loads the `codefast.config.js` for a workspace root, reporting schema warnings along the way.
  *

package/dist/core/config.js

@@ -1,7 +1,7 @@
-import { loadConfigPayload } from "#/core/config/loader";
-import { reportSchemaWarnings } from "#/core/config/warnings";
-import { AppError, messageFrom } from "#/core/errors";
-import { err, ok } from "#/core/result";
+import { loadConfigPayload } from "#core/config/loader";
+import { reportSchemaWarnings } from "#core/config/warnings";
+import { AppError, messageFrom } from "#core/errors";
+import { err, ok } from "#core/result";
 /**
  * Loads the `codefast.config.js` for a workspace root, reporting schema warnings along the way.
  *

package/dist/core/filesystem/filesystem.d.ts

@@ -32,10 +32,9 @@ export interface Filesystem {
     readdirSync(filePath: string): Array<string>;
     readFile(filePath: string, encoding: CliFileEncoding): Promise<string>;
     writeFile(filePath: string, data: string, encoding: CliFileEncoding): Promise<void>;
-    readdir(filePath: string, options?: {
-        recursive?: boolean;
-        withFileTypes?: boolean;
-    }): Promise<Array<string> | Array<DirectoryEntry>>;
+    readdirEntries(filePath: string, options?: {
+        readonly recursive?: boolean | undefined;
+    }): Promise<Array<DirectoryEntry>>;
     globSync(pattern: string, options: {
         readonly cwd: string;
     }): Array<string>;

package/dist/core/filesystem/node.d.ts

@@ -1,4 +1,4 @@
-import type { Filesystem } from "#/core/filesystem/filesystem";
+import type { Filesystem } from "#core/filesystem/filesystem";
 /**
  * The `Filesystem` implementation backed by Node's real filesystem.
  *

package/dist/core/filesystem/node.js

@@ -22,13 +22,7 @@ export const nodeFilesystem = {
     },
     readFile: (filePath, enc) => fsPromises.readFile(filePath, enc),
     writeFile: (filePath, data, enc) => fsPromises.writeFile(filePath, data, enc),
-    readdir: async (filePath, opts) => {
-        const raw = await fsPromises.readdir(filePath, opts);
-        if (!opts?.withFileTypes) {
-            return raw;
-        }
-        return raw;
-    },
+    readdirEntries: (filePath, options) => fsPromises.readdir(filePath, { recursive: options?.recursive ?? false, withFileTypes: true }),
     globSync: (pattern, options) => fsSync.globSync(pattern, options),
     rename: (oldPath, newPath) => fsPromises.rename(oldPath, newPath),
     unlink: (filePath) => fsPromises.unlink(filePath),

package/dist/core/oxc-node.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The structural view every module that walks `oxc-parser`'s ESTree output reads nodes through.
+ */
+/**
+ * An oxc ESTree node: a `type` discriminant, UTF-16 `start`/`end` offsets, and fields read by name.
+ *
+ * @remarks Structural on purpose: the walkers match node shapes by `type` and read the few fields
+ * they need, so the parser's full node union never has to be spelled out.
+ *
+ * @since 0.13.0
+ */
+export interface OxcNode {
+    readonly type: string;
+    readonly start: number;
+    readonly end: number;
+    readonly [key: string]: unknown;
+}
+/**
+ * Returns whether a value is an ESTree node rather than a scalar, a list or a location record.
+ *
+ * @since 0.13.0
+ */
+export declare function isOxcNode(value: unknown): value is OxcNode;
+/**
+ * Returns a parsed program's top-level statements.
+ *
+ * @remarks Takes `parseSync(...).program` as it comes, so no caller asserts the parser's type onto
+ * the structural view.
+ *
+ * @since 0.13.0
+ */
+export declare function programStatements(program: unknown): ReadonlyArray<OxcNode>;

package/dist/core/oxc-node.js

@@ -0,0 +1,25 @@
+/**
+ * The structural view every module that walks `oxc-parser`'s ESTree output reads nodes through.
+ */
+/**
+ * Returns whether a value is an ESTree node rather than a scalar, a list or a location record.
+ *
+ * @since 0.13.0
+ */
+export function isOxcNode(value) {
+    return typeof value === "object" && value !== null && "type" in value && typeof value.type === "string";
+}
+/**
+ * Returns a parsed program's top-level statements.
+ *
+ * @remarks Takes `parseSync(...).program` as it comes, so no caller asserts the parser's type onto
+ * the structural view.
+ *
+ * @since 0.13.0
+ */
+export function programStatements(program) {
+    if (!isOxcNode(program) || !Array.isArray(program.body)) {
+        return [];
+    }
+    return program.body.filter(isOxcNode);
+}

package/dist/core/schema-parse.d.ts

@@ -1,6 +1,6 @@
 import type { ZodType } from "zod";
-import { AppError } from "#/core/errors";
-import type { Result } from "#/core/result";
+import { AppError } from "#core/errors";
+import type { Result } from "#core/result";
 /**
  * Parses an input against a Zod schema and returns a `Result` with the value or a validation `AppError`.
  *

package/dist/core/schema-parse.js

@@ -1,5 +1,5 @@
-import { AppError } from "#/core/errors";
-import { err, ok } from "#/core/result";
+import { AppError } from "#core/errors";
+import { err, ok } from "#core/result";
 function formatSchemaIssues(issues) {
     return issues
         .map((issue) => {

package/dist/core/source-position.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Where an offset sits in a source text, as the audits report it.
+ */
+/**
+ * Returns the one-based line an offset falls on.
+ *
+ * @since 0.13.0
+ */
+export declare function lineOfOffset(sourceText: string, offset: number): number;
+/**
+ * Returns a text up to its first line break, so a multi-line node reports as one line.
+ *
+ * @since 0.13.0
+ */
+export declare function firstLineOf(text: string): string;

package/dist/core/source-position.js

@@ -0,0 +1,26 @@
+/**
+ * Where an offset sits in a source text, as the audits report it.
+ */
+/**
+ * Returns the one-based line an offset falls on.
+ *
+ * @since 0.13.0
+ */
+export function lineOfOffset(sourceText, offset) {
+    let line = 1;
+    for (let index = 0; index < offset; index++) {
+        if (sourceText.charCodeAt(index) === 10) {
+            line++;
+        }
+    }
+    return line;
+}
+/**
+ * Returns a text up to its first line break, so a multi-line node reports as one line.
+ *
+ * @since 0.13.0
+ */
+export function firstLineOf(text) {
+    const newlineIndex = text.indexOf("\n");
+    return newlineIndex === -1 ? text : text.slice(0, newlineIndex);
+}