用途:projectfmt 是生成源码与目标项目之间的格式化边界。在写入最终文件前,把源码字符串、目标路径和项目边界交给它,按目标项目自身的 Prettier、Biome 或 Deno 配置格式化。
主要能力:支持 Node/npm 的 projectfmt 与 Deno/JSR 的 @gadicc/projectfmt;核心函数 formatSource 接收源码与 { filePath, projectRoot },返回格式化结果。目标文件无需存在,但其路径决定配置发现、解析器选择、忽略规则、插件与 monorepo 选择。formatSourceWithResult 提供 changed、ignored 或完整解析诊断;resolveFormatter 可在不格式化的情况下诊断选择结果。
使用方式:Node 用 import { formatSource } from "projectfmt";Deno 用 import { formatSource } from "@gadicc/projectfmt"。调用示例:const formatted = await formatSource(rendered, { filePath, projectRoot }); 再写入文件。已知项目边界时优先显式传 projectRoot,发现不会向上搜索;仅当确实需要自动推断根目录时才用绝对路径简写 formatSource(source, absoluteFilePath)。默认 formatter: "auto" 尊重目标项目;strict: true 在无配置或同级歧义时失败,非严格 auto 在无配置时返回原源码;formatOnly: true 禁止 lint 修复与 assist,使 Biome 从 check --write 变为仅格式化;formatter: "none" 为显式退出格式化。相对 filePath 必须显式提供 projectRoot,且路径须解析为该边界内的后代文件。
错误与限制:FormatterResolutionError 处理无效选项、严格模式歧义、缺少配置或所选实现不可用;FormatterExecutionError 处理配置、解析、加载或子进程失败,包装时保留结构化字段、stderr 与 cause。所选格式化器不可用时不得回退到其他候选。目标项目视为可信代码:Prettier 配置与插件可执行 JavaScript,Biome 运行项目本地原生二进制,Deno fmt 运行 PATH 上的 deno;projectRoot 只限定发现与解析范围,不是沙箱。集成不应添加网络访问、包安装或临时目标文件,目标项目需已提供所选格式化器实现。内置适配器覆盖 Prettier、Biome、Deno;自定义 FormatterAdapter 仅在确有不同格式化器或项目信号时使用,通常需显式 projectRoot,并实现 discover、probe、format 三阶段。官方未提供的内容暂未说明。