From 4213dbc7d77963f2dd5dceeb21bdf1cb51127524 Mon Sep 17 00:00:00 2001 From: Zander Zhang <276678881@qq.com> Date: Mon, 7 Sep 2026 22:10:19 +0800 Subject: [PATCH 1/8] feat: add architecture queries and agent diagnostics --- README.md | 69 ++++++++ README.zh-CN.md | 36 ++++ .../anatomies/cli-source.anatomy.json | 45 +++++ apps/anatomy-cli/src/agent-workflow.spec.ts | 125 ++++++++++++++ apps/anatomy-cli/src/cli-arguments.spec.ts | 8 + apps/anatomy-cli/src/cli-arguments.ts | 15 ++ apps/anatomy-cli/src/cli.ts | 25 ++- .../src/format-agent-result.spec.ts | 54 ++++++ apps/anatomy-cli/src/format-agent-result.ts | 118 +++++++++++++ apps/anatomy-cli/src/index.ts | 1 + apps/anatomy-cli/src/main.ts | 5 +- apps/anatomy-cli/src/source-contract.spec.ts | 21 +++ .../anatomy/src/core/anatomy-rule-paths.ts | 15 ++ packages/anatomy/src/core/check-anatomy.ts | 158 +----------------- packages/anatomy/src/core/index.ts | 3 + .../anatomy/src/core/match-anatomy-name.ts | 157 +++++++++++++++++ .../anatomy/src/core/query-anatomy.spec.ts | 145 ++++++++++++++++ packages/anatomy/src/core/query-anatomy.ts | 110 ++++++++++++ .../src/anatomy/AnatomyBinding.schema.ts | 2 +- .../AnatomyCheckWithDiagnosticsSchema.ts | 25 +++ .../src/anatomy/AnatomyContract.spec.ts | 38 +++++ .../src/anatomy/AnatomyDraftInput.schema.ts | 2 +- .../src/anatomy/AnatomyFileEntry.schema.ts | 2 +- .../anatomy/AnatomyNameExpression.schema.ts | 4 +- .../src/anatomy/AnatomyOneOfGroup.schema.ts | 2 +- .../src/anatomy/AnatomyPolicy.schema.ts | 2 +- .../anatomy/AnatomyPolicyOverrides.schema.ts | 2 +- .../AnatomyQueryWithConstraintsSchema.ts | 38 +++++ .../src/anatomy/AnatomyStructure.schema.ts | 4 +- packages/schemas/src/anatomy/index.ts | 2 + 30 files changed, 1061 insertions(+), 172 deletions(-) create mode 100644 apps/anatomy-cli/src/agent-workflow.spec.ts create mode 100644 apps/anatomy-cli/src/format-agent-result.spec.ts create mode 100644 apps/anatomy-cli/src/format-agent-result.ts create mode 100644 apps/anatomy-cli/src/source-contract.spec.ts create mode 100644 packages/anatomy/src/core/anatomy-rule-paths.ts create mode 100644 packages/anatomy/src/core/match-anatomy-name.ts create mode 100644 packages/anatomy/src/core/query-anatomy.spec.ts create mode 100644 packages/anatomy/src/core/query-anatomy.ts create mode 100644 packages/schemas/src/anatomy/AnatomyCheckWithDiagnosticsSchema.ts create mode 100644 packages/schemas/src/anatomy/AnatomyContract.spec.ts create mode 100644 packages/schemas/src/anatomy/AnatomyQueryWithConstraintsSchema.ts diff --git a/README.md b/README.md index c760218..614cebb 100644 --- a/README.md +++ b/README.md @@ -195,6 +195,75 @@ The supported built-ins are `PascalCase`, `camelCase`, `kebab-case`, when `^` and `$` are omitted. A placeholder captured by a directory is reused by matching descendants; each repeated directory gets its own captured value. +## Agent workflow (source checkout) + +Query the definition before editing, then check the resulting file tree. These +commands use this checkout; the query interface requires a future CLI release +before it is available in registry installs. + +```bash +# Use the same target root and definition for both operations. +# The queried path is relative to the target root and may not exist yet. +bun run anatomy ./packages/services --query src/UserService/UserService.ts \ + --definition ./apps/anatomy-cli/anatomies/service-files.anatomy.json --format json + +# After the Agent creates or edits the module: +bun run anatomy ./packages/services \ + --definition ./apps/anatomy-cli/anatomies/service-files.anatomy.json --format json +``` + +Replace `./packages/services` with an existing directory in your repository. +Omit `--definition` to use the nearest `anatomy.json`, as with normal checks. +The definition root always describes the directory passed as `target`; finding +a definition in a parent does not change that root. `--query .` returns root +constraints. Relative Windows separators are accepted; absolute paths and `..` +segments in the query are rejected. Query mode reads the target to surface +filesystem errors, but never creates files or changes the definition. + +Omit `--format json` for a readable summary of required files, quantities, +inherited names, policies and conditional one-of alternatives. This summary +describes constraints; it does not certify that the files pass validation. + +Query JSON uses `contractVersion: 1`, `operation: "query"`, and these statuses: + +| Status | Meaning | +| --- | --- | +| `resolved` | A declared rule was found, or root constraints were requested. This is not a validation pass. | +| `unmatched` | No entry rule matched at `scopePath`; that parent's `unexpectedEntry` policy still applies. Undeclared directory descendants are not checked. | +| `mismatch` | A name, binding, or intermediate entry kind conflicts with the declared structure. | +| `ambiguous` | Multiple rules may consume the entry; inspect `matches` and `rules`. Validation uses definition order, entry kinds and siblings. | + +Responses include the absolute definition and target paths, effective policies, +captured placeholder values, binding constraints, ancestor quantities, applicable +rules and containing one-of groups. Directory rules retain their child structure. +Use `captures` to substitute inherited placeholders in descendants; one-of +alternatives are conditional, not a list of files that must all be created. +Always run a check to evaluate quantities, sibling alternatives and actual kinds. + +Check JSON preserves `conforms`, `summary`, and the existing issue fields, adding +`contractVersion: 1`, `operation: "check"`, definition/target metadata and +`ignoredNames`. Each issue adds `rulePath` (a JSON Pointer into the definition), +`expected` (the declared node), and `actual` (observed entry summaries). For +missing-entry and one-of issues, `actual` lists siblings in the affected directory. +Unexpected entries have null `rulePath` and `expected`. Use `rulePath` to correlate +query and check results for the same definition revision: omitted IDs are generated +anew when parsing, and array indices can change when the definition is edited. + +A completed query exits `0` for every query status; inspect `status` before +editing. Checks retain `0` for no blocking findings and `1` for blocking findings. +Operational errors exit `2`; with `--format json`, stderr contains an +`operation: "error"` JSON object and stdout has no success report. Missing or +invalid definitions, unsupported schema versions, unknown fields and unreadable +targets are errors, not an absence of constraints. Unknown definition fields are +now rejected instead of silently removed; fix spelling or use supported version-1 +rules. Human check output and legacy target/definition flags remain supported. + +Queries describe declared structure independently of scan exclusions, so `--ignore` +is only accepted for checks. Checks continue to skip symbolic links and default +generated directories, including `node_modules` and `dist`; the report lists +ignored names. A structural pass only covers the collected tree and executed +rules. Run type checks and behavior tests separately. + ## Development ```bash diff --git a/README.zh-CN.md b/README.zh-CN.md index ced865b..a254131 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -164,6 +164,42 @@ Anatomy JSON 定义只需包含供人阅读的元数据和结构约束。可以 目录捕获的占位符值会被匹配到的后代节点复用;每个重复目录都有各自独立的捕获值。 +## Agent 工作流(源码运行) + +修改前查询定义,修改后检查文件树。以下命令使用当前源码;查询接口需要后续发布新版 CLI 才能通过包管理器安装使用。 + +```bash +# 两次操作使用相同的目标根目录和定义。 +# 查询路径相对于目标根目录,可以尚不存在。 +bun run anatomy ./packages/services --query src/UserService/UserService.ts \ + --definition ./apps/anatomy-cli/anatomies/service-files.anatomy.json --format json + +# Agent 创建或修改模块后: +bun run anatomy ./packages/services \ + --definition ./apps/anatomy-cli/anatomies/service-files.anatomy.json --format json +``` + +将 `./packages/services` 替换为仓库中实际存在的目录。省略 `--definition` 时,仍向上查找最近的 `anatomy.json`。定义的根节点始终描述传入的目标目录;在父目录找到定义不会改变这个对应关系。`--query .` 返回根约束。查询路径支持 Windows 相对路径分隔符,拒绝绝对路径和 `..` 路径段。查询会读取目标以发现文件系统错误,不创建文件或改写定义。 + +省略 `--format json` 时,直接显示文件要求、数量、继承名称、策略和 one-of 条件选择的可读摘要。摘要描述的是约束,不代表实际文件已通过检查。 + +查询 JSON 使用 `contractVersion: 1`、`operation: "query"`,状态含义如下: + +| 状态 | 含义 | +| --- | --- | +| `resolved` | 找到声明的规则,或正在查询根约束;不代表验证通过。 | +| `unmatched` | 在 `scopePath` 下没有匹配的节点规则;该父目录的 `unexpectedEntry` 策略仍然适用。未声明目录的后代不会被检查。 | +| `mismatch` | 名称、占位符绑定或中间路径的节点类型与定义冲突。 | +| `ambiguous` | 多条规则可能消费同一节点,需要查看 `matches` 和 `rules`;实际检查还取决于规则顺序、节点类型和同级条目。 | + +响应包含定义及目标的绝对路径、有效策略、占位符捕获值、绑定约束、祖先数量约束、相关规则和所属 one-of 组。目录规则保留子树;可用 `captures` 替换后代中的继承占位符。one-of 的候选项是条件选择,不是全部必须创建的文件。数量、同级候选项和实际节点类型仍须在修改后执行检查。 + +检查 JSON 保留 `conforms`、`summary` 和原有诊断字段,新增 `contractVersion: 1`、`operation: "check"`、定义及目标信息、`ignoredNames`。每条诊断新增 `rulePath`(定义中的 JSON Pointer)、`expected`(声明的节点)和 `actual`(实际条目摘要)。缺失节点与 one-of 诊断的 `actual` 列出受影响目录下的同级条目;意外节点的 `rulePath`、`expected` 为 null。用 `rulePath` 关联同一版定义的查询与检查:省略的 ID 每次解析都会重新生成,编辑定义后数组下标也可能变化。 + +查询完成时所有查询状态均返回退出码 `0`,Agent 应读取 `status` 再决定如何修改。检查仍以 `0` 表示没有阻断项、`1` 表示存在阻断项。运行错误返回 `2`;指定 `--format json` 时,stderr 输出 `operation: "error"` 的 JSON,stdout 不输出成功报告。定义缺失或无效、版本不支持、未知字段和目标不可读都属于错误,不能视为“没有约束”。未知定义字段现在会被拒绝,不再静默移除;需要修正拼写或使用已支持的版本 1 规则。原有人类可读检查输出和目标、定义参数保持可用。 + +查询描述声明的结构,不应用扫描忽略规则,因此 `--ignore` 只接受于检查模式。检查仍跳过符号链接以及 `node_modules`、`dist` 等默认生成目录,报告会列出忽略名称。结构检查通过仅覆盖已采集文件树与已执行规则;类型和行为须另行验证。 + ## 开发 ```bash diff --git a/apps/anatomy-cli/anatomies/cli-source.anatomy.json b/apps/anatomy-cli/anatomies/cli-source.anatomy.json index b919552..5e2fedd 100644 --- a/apps/anatomy-cli/anatomies/cli-source.anatomy.json +++ b/apps/anatomy-cli/anatomies/cli-source.anatomy.json @@ -55,6 +55,51 @@ "kind": "file", "name": { "type": "literal", "value": "format-result.ts" }, "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "agent-workflow.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "format-agent-result.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "format-agent-result.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "source-contract.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "install-main.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "install-options.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "install-path.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "install.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "install.ts" }, + "quantity": "exactly_one" } ] } diff --git a/apps/anatomy-cli/src/agent-workflow.spec.ts b/apps/anatomy-cli/src/agent-workflow.spec.ts new file mode 100644 index 0000000..fca95b7 --- /dev/null +++ b/apps/anatomy-cli/src/agent-workflow.spec.ts @@ -0,0 +1,125 @@ +import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; +import { resolve, join } from "node:path"; +import { afterEach, beforeEach, describe, expect, it } from "vitest"; +import { AnatomyCheckWithDiagnosticsSchema, AnatomyQueryWithConstraintsSchema } from "@anatomy-cli/schemas"; +import { runAnatomyCli, type AnatomyCliDependencies } from "./cli"; +import { collectFileTree, findAnatomyDefinition, readAnatomyDefinition } from "./filesystem"; +import { formatAgentError } from "./format-agent-result"; + +const verificationRoot = resolve(import.meta.dirname, "../../../docs/verification/agent-workflow-tests"); +let directory: string; +const document = () => ({ + name: "Services", purpose: "Plan before creating modules", + structure: { + schemaVersion: 1, + defaultPolicies: { missingRequired: "block", unexpectedEntry: "block", nameMismatch: "block", nestingMismatch: "block" }, + bindings: { Name: { format: "PascalCase" } }, + root: { children: [{ + kind: "directory", name: { type: "placeholder", value: "Service" }, quantity: "one_or_more", + children: [{ kind: "file", name: { type: "placeholder", value: "Service.ts" }, quantity: "exactly_one" }], + }] }, + }, +}); + +beforeEach(async () => { + await mkdir(verificationRoot, { recursive: true }); + directory = await mkdtemp(join(verificationRoot, "case-")); + await writeFile(join(directory, "anatomy.json"), JSON.stringify(document())); +}); + +afterEach(async () => { await rm(directory, { recursive: true, force: true }); }); + +const invoke = async (args: string[]) => { + const output: string[] = []; + const dependencies: AnatomyCliDependencies = { + findDefinition: findAnatomyDefinition, readDefinition: async (path) => readAnatomyDefinition(path), + collectTree: collectFileTree, writeOutput: (value) => output.push(value), + }; + const result = await runAnatomyCli([directory, ...args, "--format", "json"], dependencies); + return { result, output: output.join("\n") }; +}; + +describe("Agent query-edit-check workflow", () => { + it("queries a missing file, catches a wrong name, and validates a corrected module", async () => { + const queried = await invoke(["--query", "UserService/UserService.ts"]); + expect(queried.result._unsafeUnwrap()).toBe(0); + const query = AnatomyQueryWithConstraintsSchema.parse(JSON.parse(queried.output)); + expect(query.status).toBe("resolved"); + expect(query.captures).toEqual({ Name: "User" }); + await mkdir(join(directory, "UserService")); + await writeFile(join(directory, "UserService", "OrderService.ts"), "export const service = {};\n"); + const blocked = await invoke([]); + expect(blocked.result._unsafeUnwrap()).toBe(1); + const report = AnatomyCheckWithDiagnosticsSchema.parse(JSON.parse(blocked.output)); + expect(report.issues[0]).toMatchObject({ + code: "binding_consistency_mismatch", rulePath: query.matches[0], + actual: [{ kind: "file", name: "OrderService.ts" }], + expected: { name: { value: "Service.ts" } }, + }); + expect(report.definition.path).toBe(join(directory, "anatomy.json")); + expect(report.targetPath).toBe(directory); + expect(report.ignoredNames).toContain("node_modules"); + await rm(join(directory, "UserService", "OrderService.ts")); + await writeFile(join(directory, "UserService", "UserService.ts"), "export const service = {};\n"); + const passed = await invoke([]); + expect(passed.result._unsafeUnwrap()).toBe(0); + expect(JSON.parse(passed.output)).toMatchObject({ conforms: true, issues: [] }); + }); + + it("provides actual sibling entries for a missing required file", async () => { + await mkdir(join(directory, "UserService")); + await writeFile(join(directory, "UserService", "extra.txt"), ""); + const checked = await invoke([]); + const report = AnatomyCheckWithDiagnosticsSchema.parse(JSON.parse(checked.output)); + expect(report.issues.find((issue) => issue.code === "missing_required")).toMatchObject({ + path: "UserService", actual: [{ kind: "file", name: "extra.txt" }], + rulePath: "/structure/root/children/0/children/0", + }); + expect(report.issues.find((issue) => issue.code === "unexpected_entry")).toMatchObject({ + path: "UserService/extra.txt", rulePath: null, expected: null, + }); + }); + + it.each([{ args: [] }, { args: ["--query", "unmatched"] }])("rejects unsupported constraints in both modes: $args", async ({ args }) => { + const invalid = document(); + Object.assign(invalid.structure, { dependencyRules: [] }); + await writeFile(join(directory, "anatomy.json"), JSON.stringify(invalid)); + const run = await invoke(args); + expect(run.result.isErr()).toBe(true); + expect(run.output).toBe(""); + const error = JSON.parse(formatAgentError(run.result._unsafeUnwrapErr())); + expect(error).toMatchObject({ operation: "error", error: { code: "AnatomyDefinitionFileError" } }); + }); + + it("reports an unreadable definition as an operational error", async () => { + const run = await invoke(["--definition", join(directory, "missing.json")]); + expect(run.result.isErr()).toBe(true); + expect(run.output).toBe(""); + }); + + it("does not report success when the target cannot be read", async () => { + const output: string[] = []; + const result = await runAnatomyCli([join(directory, "missing"), "--query", ".", + "--definition", join(directory, "anatomy.json"), "--format", "json"], { + findDefinition: findAnatomyDefinition, readDefinition: async (path) => readAnatomyDefinition(path), + collectTree: collectFileTree, writeOutput: (value) => output.push(value), + }); + expect(result.isErr()).toBe(true); + expect(result._unsafeUnwrapErr().name).toBe("AnatomyFileTreeError"); + expect(output).toEqual([]); + }); + + it("uses the same explicit root for discovery, querying and checking", async () => { + const scope = join(directory, "scope"); + await mkdir(scope); + const output: string[] = []; + const result = await runAnatomyCli([scope, "--query", "UserService", "--format", "json"], { + findDefinition: findAnatomyDefinition, readDefinition: async (path) => readAnatomyDefinition(path), + collectTree: collectFileTree, writeOutput: (value) => output.push(value), + }); + expect(result._unsafeUnwrap()).toBe(0); + expect(JSON.parse(output[0]!)).toMatchObject({ targetPath: scope, + definition: { path: join(directory, "anatomy.json") }, status: "resolved", + }); + }); +}); diff --git a/apps/anatomy-cli/src/cli-arguments.spec.ts b/apps/anatomy-cli/src/cli-arguments.spec.ts index c62ff83..8d807a8 100644 --- a/apps/anatomy-cli/src/cli-arguments.spec.ts +++ b/apps/anatomy-cli/src/cli-arguments.spec.ts @@ -2,6 +2,13 @@ import { describe, expect, it } from "vitest"; import { parseCliArguments } from "./cli-arguments"; describe("parseCliArguments", () => { + it("supports query mode without reserving existing target directory names", () => { + expect(parseCliArguments(["query", "--query", "new/file.ts"])._unsafeUnwrap()) + .toMatchObject({ targetPath: "query", queryPath: "new/file.ts" }); + expect(parseCliArguments(["--query"]).isErr()).toBe(true); + expect(parseCliArguments(["--query", ".", "--query", "src"]).isErr()).toBe(true); + expect(parseCliArguments(["--query", ".", "--ignore", "src"]).isErr()).toBe(true); + }); it("parses the target, explicit definition, output format, and repeated ignores", () => { const result = parseCliArguments([ "src", @@ -21,6 +28,7 @@ describe("parseCliArguments", () => { format: "json", ignore: ["generated", "temp", "fixtures"], help: false, + queryPath: null, }); }); diff --git a/apps/anatomy-cli/src/cli-arguments.ts b/apps/anatomy-cli/src/cli-arguments.ts index a592917..d062940 100644 --- a/apps/anatomy-cli/src/cli-arguments.ts +++ b/apps/anatomy-cli/src/cli-arguments.ts @@ -8,6 +8,7 @@ export type AnatomyCliOptions = { format: (typeof AnatomyCliFormatValues)[number]; ignore: string[]; help: boolean; + queryPath: string | null; }; export class AnatomyCliArgumentError extends Error { @@ -38,6 +39,7 @@ export const parseCliArguments = ( format: "human", ignore: [], help: false, + queryPath: null, }; const consumedIndexes = new Set(); let targetSpecified = false; @@ -59,6 +61,15 @@ export const parseCliArguments = ( continue; } + if (argument === "--query") { + if (options.queryPath !== null) return err(new AnatomyCliArgumentError("Query path may only be specified once")); + const value = getOptionValue(args, index, argument); + if (value.isErr()) return err(value.error); + options.queryPath = value.value; + consumedIndexes.add(index + 1); + continue; + } + if (argument === "--target" || argument === "-t") { if (targetSpecified) { return err(new AnatomyCliArgumentError("Target directory may only be specified once")); @@ -108,6 +119,9 @@ export const parseCliArguments = ( return err(new AnatomyCliArgumentError(`Unknown argument "${argument}"`)); } + if (options.queryPath !== null && options.ignore.length > 0) { + return err(new AnatomyCliArgumentError("--ignore is only supported for checks; queries describe declared constraints")); + } return ok(options); }; @@ -121,6 +135,7 @@ export const AnatomyCliUsage = [ " -d, --definition Anatomy JSON (default: nearest anatomy.json)", " -t, --target Alternate form of the target argument", " --format human or json (default: human)", + " --query Query constraints relative to target (path may not exist)", " --ignore Comma-separated names; may be repeated", " -h, --help Show this help", ].join("\n"); diff --git a/apps/anatomy-cli/src/cli.ts b/apps/anatomy-cli/src/cli.ts index 85d0813..d865efc 100644 --- a/apps/anatomy-cli/src/cli.ts +++ b/apps/anatomy-cli/src/cli.ts @@ -1,15 +1,16 @@ import { err, ok, type Result } from "neverthrow"; -import { checkAnatomy, type AnatomyFileTreeEntry } from "@anatomy-cli/anatomy/core"; +import { checkAnatomy, queryAnatomy, type AnatomyFileTreeEntry } from "@anatomy-cli/anatomy/core"; import type { AnatomyDraftInput } from "@anatomy-cli/schemas"; import { AnatomyCliUsage, parseCliArguments, type AnatomyCliOptions } from "./cli-arguments"; import { collectFileTree, findAnatomyDefinition, readAnatomyDefinition, - type AnatomyDefinitionFileError, + AnatomyDefinitionFileError, type AnatomyFileTreeError, } from "./filesystem"; -import { formatHumanResult, formatJsonResult } from "./format-result"; +import { formatHumanResult } from "./format-result"; +import { formatAgentCheck, formatAgentQuery } from "./format-agent-result"; export const AnatomyCliExitCode = { success: 0, @@ -63,17 +64,31 @@ export const runAnatomyCli = async ( const tree = await dependencies.collectTree(options.targetPath, options.ignore); if (tree.isErr()) return err(tree.error); + if (options.queryPath !== null) { + const queried = queryAnatomy(definition.value, options.queryPath); + if (queried.isErr()) { + return err(Array.isArray(queried.error) + ? new AnatomyDefinitionFileError(queried.error.map((issue) => issue.message).join("; "), definitionPath.value) + : queried.error); + } + dependencies.writeOutput(formatAgentQuery(queried.value, definition.value, + definitionPath.value, options.targetPath, options.format)); + return ok(AnatomyCliExitCode.success); + } + const checked = checkAnatomy(definition.value, tree.value); if (checked.isErr()) { return err( - new Error( + new AnatomyDefinitionFileError( `Anatomy definition failed structural validation: ${checked.error.map((issue) => issue.message).join("; ")}`, + definitionPath.value, ), ); } dependencies.writeOutput( - options.format === "json" ? formatJsonResult(checked.value) : formatHumanResult(checked.value), + options.format === "json" ? formatAgentCheck(checked.value, definition.value, + definitionPath.value, options.targetPath, tree.value, options.ignore) : formatHumanResult(checked.value), ); return ok(checked.value.conforms ? AnatomyCliExitCode.success : AnatomyCliExitCode.blocked); diff --git a/apps/anatomy-cli/src/format-agent-result.spec.ts b/apps/anatomy-cli/src/format-agent-result.spec.ts new file mode 100644 index 0000000..c80d69d --- /dev/null +++ b/apps/anatomy-cli/src/format-agent-result.spec.ts @@ -0,0 +1,54 @@ +import { describe, expect, it } from "vitest"; +import { AnatomyDraftInputSchema } from "@anatomy-cli/schemas"; +import { queryAnatomy } from "@anatomy-cli/anatomy/core"; +import { formatAgentQuery } from "./format-agent-result"; + +const definition = AnatomyDraftInputSchema.parse({ + name: "Readable query", purpose: "Show constraints before editing", + structure: { + schemaVersion: 1, + defaultPolicies: { missingRequired: "block", unexpectedEntry: "block", nameMismatch: "block", nestingMismatch: "block" }, + bindings: { Name: { format: "PascalCase" } }, + root: { children: [{ + kind: "directory", name: { type: "placeholder", value: "Service" }, quantity: "one_or_more", + children: [{ + kind: "one_of", minimumMatches: 1, maximumMatches: 1, + alternatives: ["ts", "js"].map((extension) => ({ + kind: "file", name: { type: "placeholder", value: `Service.${extension}` }, quantity: "exactly_one", + policyOverrides: { missingRequired: "warn" }, + })), + }], + }] }, + }, +}); + +describe("human query output", () => { + it("explains inherited names, optional alternatives and policy overrides without a JSON dump", () => { + const query = queryAnatomy(definition, "UserService")._unsafeUnwrap(); + const text = formatAgentQuery(query, definition, "anatomy.json", ".", "human"); + expect(text).toContain("directory UserService — required, one or more"); + expect(text).toContain("Choose 1-1 alternatives (requirements below apply when selected)"); + expect(text).toContain("file UserService.ts — required exactly once"); + expect(text).toContain("Missing entries: WARN"); + expect(text).toContain("Captured = User"); + expect(text).toContain("Binding : PascalCase"); + expect(text).toContain("Query only."); + expect(text).not.toContain('"contractVersion"'); + }); + + it("keeps unresolved paths visibly different from validation passes", () => { + const query = queryAnatomy(definition, "extra/child")._unsafeUnwrap(); + const text = formatAgentQuery(query, definition, "anatomy.json", ".", "human"); + expect(text).toContain("UNMATCHED"); + expect(text).toContain(query.reason); + expect(text).toContain("Extra entries: BLOCK"); + expect(text).not.toContain("PASS"); + }); + + it("preserves the machine-readable response and metadata", () => { + const query = queryAnatomy(definition, "UserService/UserService.ts")._unsafeUnwrap(); + const report = JSON.parse(formatAgentQuery(query, definition, "anatomy.json", ".", "json")); + expect(report).toMatchObject(query); + expect(report.definition).toMatchObject({ name: definition.name, schemaVersion: 1 }); + }); +}); diff --git a/apps/anatomy-cli/src/format-agent-result.ts b/apps/anatomy-cli/src/format-agent-result.ts new file mode 100644 index 0000000..243ab42 --- /dev/null +++ b/apps/anatomy-cli/src/format-agent-result.ts @@ -0,0 +1,118 @@ +import { resolve } from "node:path"; +import { AnatomyCheckCode, anatomyRulePaths, type AnatomyCheckResult, type AnatomyFileTreeEntry } from "@anatomy-cli/anatomy/core"; +import type { AnatomyCheckWithDiagnostics, AnatomyDraftInput, AnatomyNode, AnatomyPolicies, AnatomyQueryWithConstraints, AnatomyQuantity } from "@anatomy-cli/schemas"; +import { DefaultIgnoredNames } from "./filesystem"; + +export const formatAgentCheck = ( + result: AnatomyCheckResult, + definition: AnatomyDraftInput, + definitionPath: string, + targetPath: string, + tree: AnatomyFileTreeEntry[], + ignore: string[], +): string => { + const rules = anatomyRulePaths(definition); + const actualByPath = new Map([[".", tree]]); + const visit = (entries: AnatomyFileTreeEntry[], parent: string): void => { + for (const entry of entries) { + const path = parent ? `${parent}/${entry.name}` : entry.name; + actualByPath.set(path, [entry]); + if (entry.kind === "directory") visit(entry.children, path); + } + }; + visit(tree, ""); + const report: AnatomyCheckWithDiagnostics = { + ...result, contractVersion: 1, operation: "check", + definition: { path: resolve(definitionPath), name: definition.name, schemaVersion: definition.structure.schemaVersion }, + targetPath: resolve(targetPath), ignoredNames: [...new Set([...DefaultIgnoredNames, ...ignore])], + issues: result.issues.map((issue) => { + const rule = issue.constraintId ? rules.get(issue.constraintId) : undefined; + const entries = actualByPath.get(issue.path) ?? []; + const actual = issue.code === AnatomyCheckCode.missingRequired || issue.code === AnatomyCheckCode.oneOfMismatch + ? issue.path === "." ? tree : entries.flatMap((entry) => entry.kind === "directory" ? entry.children : []) + : entries; + return { + ...issue, rulePath: rule?.rulePath ?? null, expected: rule?.node ?? null, + actual: actual.map(({ kind, name }) => ({ kind, name })), + }; + }), + }; + return JSON.stringify(report, null, 2); +}; + +export const formatAgentQuery = ( + result: AnatomyQueryWithConstraints, + definition: AnatomyDraftInput, + definitionPath: string, + targetPath: string, + format: "human" | "json", +): string => { + const report = { + ...result, + definition: { path: resolve(definitionPath), name: definition.name, schemaVersion: definition.structure.schemaVersion }, + targetPath: resolve(targetPath), + }; + if (format === "json") return JSON.stringify(report, null, 2); + + const quantities: Record = { + exactly_one: "required exactly once", + optional: "optional, at most once", + one_or_more: "required, one or more", + zero_or_more: "optional, any number", + }; + const policyLabels: Record = { + missingRequired: "Missing entries", + unexpectedEntry: "Extra entries", + nameMismatch: "Wrong name", + nestingMismatch: "Wrong entry kind", + }; + const policies = (values: AnatomyPolicies) => Object.entries(values) + .map(([key, value]) => `${policyLabels[key as keyof AnatomyPolicies]}: ${value.toUpperCase()}`) + .join("; "); + const ruleLines = (node: AnatomyNode, inherited: AnatomyPolicies, depth = 0): string[] => { + const indent = " ".repeat(depth); + if (node.kind === "one_of") { + return [ + `${indent}Choose ${node.minimumMatches}-${node.maximumMatches} alternatives (requirements below apply when selected):`, + ...node.alternatives.flatMap((entry) => ruleLines(entry, inherited, depth + 1)), + ]; + } + const name = node.name.type === "literal" ? node.name.value : node.name.value.replace( + /<([^<>]+)>/, (placeholder, binding: string) => result.captures[binding] ?? placeholder, + ); + const effective = { ...inherited, ...node.policyOverrides }; + const overrides = Object.entries(node.policyOverrides).filter( + ([key, value]) => inherited[key as keyof AnatomyPolicies] !== value, + ); + return [ + `${indent}${node.kind} ${name} — ${quantities[node.quantity]}`, + ...(overrides.length ? [`${indent} Policies: ${policies(effective)}`] : []), + ...(node.kind === "directory" ? node.children.flatMap((child) => ruleLines(child, effective, depth + 1)) : []), + ]; + }; + + return [ + `Anatomy query: ${result.status.toUpperCase()} (${result.path})`, + `Definition: ${report.definition.path}`, + `Target root: ${report.targetPath}`, + `Scope: ${result.scopePath}`, + result.reason ?? "", + ...result.ancestors.map((ancestor) => `Parent ${ancestor.name} — ${quantities[ancestor.quantity]}`), + ...result.rules.flatMap((rule) => [ + ...ruleLines(rule.node, rule.policies), + ` ${policies(rule.policies)}`, + ]), + ...(result.rules.length ? [] : [`No entry rules declared. ${policies(result.policies)}`]), + ...Object.entries(result.captures).map(([name, value]) => `Captured <${name}> = ${value}`), + ...Object.entries(result.bindings).map(([name, binding]) => + `Binding <${name}>: ${[binding.format, binding.pattern ? `full pattern /${binding.pattern}/` : undefined].filter(Boolean).join("; ")}`), + ...result.groups.map((group) => + `Containing one-of: choose ${group.minimumMatches}-${group.maximumMatches} alternatives (${group.rulePath})`), + "Query only. Run anatomy with the same target and definition, without --query, to check actual files.", + ].filter(Boolean).join("\n"); +}; + +export const formatAgentError = (error: Error): string => JSON.stringify({ + contractVersion: 1, operation: "error", + error: { code: error.name, message: error.message, ...("path" in error ? { path: error.path } : {}) }, +}, null, 2); diff --git a/apps/anatomy-cli/src/index.ts b/apps/anatomy-cli/src/index.ts index 866b4c9..649cc88 100644 --- a/apps/anatomy-cli/src/index.ts +++ b/apps/anatomy-cli/src/index.ts @@ -2,3 +2,4 @@ export * from "./cli"; export * from "./cli-arguments"; export * from "./filesystem"; export * from "./format-result"; +export * from "./format-agent-result"; diff --git a/apps/anatomy-cli/src/main.ts b/apps/anatomy-cli/src/main.ts index 8f6d804..4595998 100755 --- a/apps/anatomy-cli/src/main.ts +++ b/apps/anatomy-cli/src/main.ts @@ -2,6 +2,7 @@ import { AnatomyCliExitCode, runAnatomyCli } from "./cli"; import { AnatomyCliUsage } from "./cli-arguments"; +import { formatAgentError } from "./format-agent-result"; const result = await runAnatomyCli(process.argv.slice(2)); @@ -10,7 +11,9 @@ result.match( process.exitCode = exitCode; }, (error) => { - process.stderr.write(`Anatomy error: ${error.message}\n\n${AnatomyCliUsage}\n`); + const args = process.argv.slice(2); + const json = args.some((argument, index) => argument === "--format" && args[index + 1] === "json"); + process.stderr.write(json ? `${formatAgentError(error)}\n` : `Anatomy error: ${error.message}\n\n${AnatomyCliUsage}\n`); process.exitCode = AnatomyCliExitCode.operationalError; }, ); diff --git a/apps/anatomy-cli/src/source-contract.spec.ts b/apps/anatomy-cli/src/source-contract.spec.ts new file mode 100644 index 0000000..2ecc927 --- /dev/null +++ b/apps/anatomy-cli/src/source-contract.spec.ts @@ -0,0 +1,21 @@ +import { resolve } from "node:path"; +import { describe, expect, it } from "vitest"; +import { checkAnatomy } from "@anatomy-cli/anatomy/core"; +import { collectFileTree, readAnatomyDefinition } from "./filesystem"; + +describe("CLI source contract", () => { + it("checks the real source directory against the shipped example definition", async () => { + const definition = (await readAnatomyDefinition( + resolve(import.meta.dirname, "../anatomies/cli-source.anatomy.json"), + ))._unsafeUnwrap(); + const entries = (await collectFileTree(import.meta.dirname))._unsafeUnwrap(); + const result = checkAnatomy(definition, entries)._unsafeUnwrap(); + + expect(result.issues).toEqual([]); + expect(result.conforms).toBe(true); + expect(checkAnatomy(definition, entries.filter((entry) => entry.name !== "cli.ts")) + ._unsafeUnwrap().conforms).toBe(false); + expect(checkAnatomy(definition, [...entries, { kind: "file", name: "undeclared.ts" }]) + ._unsafeUnwrap().conforms).toBe(false); + }); +}); diff --git a/packages/anatomy/src/core/anatomy-rule-paths.ts b/packages/anatomy/src/core/anatomy-rule-paths.ts new file mode 100644 index 0000000..f51ee47 --- /dev/null +++ b/packages/anatomy/src/core/anatomy-rule-paths.ts @@ -0,0 +1,15 @@ +import type { AnatomyDraftInput, AnatomyNode } from "@anatomy-cli/schemas"; + +export const anatomyRulePaths = (definition: AnatomyDraftInput) => { + const rules = new Map(); + const visit = (nodes: AnatomyNode[], path: string): void => { + nodes.forEach((node, index) => { + const rulePath = `${path}/${index}`; + rules.set(node.id, { rulePath, node }); + if (node.kind === "directory") visit(node.children, `${rulePath}/children`); + if (node.kind === "one_of") visit(node.alternatives, `${rulePath}/alternatives`); + }); + }; + visit(definition.structure.root.children, "/structure/root/children"); + return rules; +}; diff --git a/packages/anatomy/src/core/check-anatomy.ts b/packages/anatomy/src/core/check-anatomy.ts index bf09fe5..8693766 100644 --- a/packages/anatomy/src/core/check-anatomy.ts +++ b/packages/anatomy/src/core/check-anatomy.ts @@ -1,8 +1,7 @@ -import { err, ok, Result, type Result as ResultType } from "neverthrow"; +import { evaluateName, type BindingScope, type NameMatch } from "./match-anatomy-name"; +import { err, ok, type Result as ResultType } from "neverthrow"; import { type AnatomyDraftInput, - type AnatomyBinding, - type AnatomyBindingFormat, type AnatomyEntry, type AnatomyNode, type AnatomyPolicies, @@ -49,15 +48,6 @@ export type AnatomyCheckResult = { }; type PolicyAncestor = { id: string; overrides: AnatomyPolicyOverrides }; -type BindingScope = Readonly>; - -type NameMatch = - | { kind: "match"; captures: Record } - | { kind: "binding_format_mismatch"; name: string; value: string; format: AnatomyBindingFormat } - | { kind: "binding_pattern_mismatch"; name: string; value: string; pattern: string } - | { kind: "binding_consistency_mismatch"; name: string; expected: string; actual: string } - | { kind: "none" }; - type NameMatchCandidate = { index: number; match: Exclude; @@ -70,150 +60,6 @@ type SuccessfulNameMatchCandidate = { type BindingMismatch = Exclude; -const escapeRegularExpression = (value: string): string => { - return value.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&"); -}; - -const createNamePattern = (entry: AnatomyEntry, ignoreCase = false): RegExp => { - if (entry.name.type === "literal") { - return new RegExp( - `^${escapeRegularExpression(entry.name.value)}$`, - ignoreCase ? "i" : undefined, - ); - } - - const openingBracket = entry.name.value.indexOf("<"); - const closingBracket = entry.name.value.indexOf(">", openingBracket + 1); - const prefix = entry.name.value.slice(0, openingBracket); - const suffix = entry.name.value.slice(closingBracket + 1); - const placeholderExpression = suffix.includes(".") ? "[^./\\\\]+" : "[^/\\\\]+"; - - return new RegExp( - `^${escapeRegularExpression(prefix)}${placeholderExpression}${escapeRegularExpression(suffix)}$`, - ignoreCase ? "i" : undefined, - ); -}; - -const parsePlaceholder = ( - entry: AnatomyEntry, -): { name: string; prefix: string; suffix: string } | undefined => { - if (entry.name.type !== "placeholder") return undefined; - - const openingBracket = entry.name.value.indexOf("<"); - const closingBracket = entry.name.value.indexOf(">", openingBracket + 1); - if (openingBracket < 0 || closingBracket < 0) return undefined; - - return { - name: entry.name.value.slice(openingBracket + 1, closingBracket), - prefix: entry.name.value.slice(0, openingBracket), - suffix: entry.name.value.slice(closingBracket + 1), - }; -}; - -const bindingFormatPatterns: Record = { - PascalCase: /^[A-Z][A-Za-z0-9]*$/, - camelCase: /^[a-z][A-Za-z0-9]*$/, - "kebab-case": /^[a-z0-9]+(?:-[a-z0-9]+)*$/, - snake_case: /^[a-z0-9]+(?:_[a-z0-9]+)*$/, - SCREAMING_SNAKE_CASE: /^[A-Z0-9]+(?:_[A-Z0-9]+)*$/, -}; - -const compilePattern = Result.fromThrowable( - (pattern: string) => new RegExp(`^(?:${pattern})$`), - () => undefined, -); - -const matchesBinding = (binding: AnatomyBinding, value: string): BindingMismatch | undefined => { - if ( - binding.format !== undefined && - (bindingFormatPatterns[binding.format] === undefined || - !bindingFormatPatterns[binding.format].test(value)) - ) { - return { - kind: "binding_format_mismatch", - name: "", - value, - format: binding.format, - }; - } - - if (binding.pattern !== undefined) { - const compiledPattern = compilePattern(binding.pattern); - if (compiledPattern.isErr()) { - return { - kind: "binding_pattern_mismatch", - name: "", - value, - pattern: binding.pattern, - }; - } - - if (!compiledPattern.value.test(value)) { - return { - kind: "binding_pattern_mismatch", - name: "", - value, - pattern: binding.pattern, - }; - } - } - - return undefined; -}; - -const evaluateName = ( - entry: AnatomyEntry, - actualName: string, - scope: BindingScope, - bindings: Readonly>, - ignoreCase = false, -): NameMatch => { - if (entry.name.type === "literal") { - return createNamePattern(entry, ignoreCase).test(actualName) - ? { kind: "match", captures: {} } - : { kind: "none" }; - } - - const placeholder = parsePlaceholder(entry); - if (!placeholder) return { kind: "none" }; - - const placeholderExpression = placeholder.suffix.includes(".") - ? "[^./\\\\]+" - : "[^/\\\\]+"; - const pattern = new RegExp( - `^${escapeRegularExpression(placeholder.prefix)}(${placeholderExpression})${escapeRegularExpression(placeholder.suffix)}$`, - ignoreCase ? "i" : undefined, - ); - const match = pattern.exec(actualName); - if (!match) return { kind: "none" }; - - const capturedValue = match[1]; - if (capturedValue === undefined) return { kind: "none" }; - - const boundValue = scope[placeholder.name]; - if (boundValue !== undefined && boundValue !== capturedValue) { - return { - kind: "binding_consistency_mismatch", - name: placeholder.name, - expected: boundValue, - actual: capturedValue, - }; - } - - const binding = bindings[placeholder.name]; - if (binding !== undefined) { - const bindingMismatch = matchesBinding(binding, capturedValue); - if (bindingMismatch !== undefined) { - return { ...bindingMismatch, name: placeholder.name }; - } - } - - return { - kind: "match", - captures: boundValue === undefined ? { [placeholder.name]: capturedValue } : {}, - }; -}; - const joinPath = (parentPath: string, name: string): string => { return parentPath === "." ? name : `${parentPath}/${name}`; }; diff --git a/packages/anatomy/src/core/index.ts b/packages/anatomy/src/core/index.ts index 78af826..e79d6a4 100644 --- a/packages/anatomy/src/core/index.ts +++ b/packages/anatomy/src/core/index.ts @@ -4,3 +4,6 @@ export * from "./createEmptyAnatomyDraft"; export * from "./resolveAnatomyPolicies"; export * from "./ResolvedAnatomyPolicy"; export * from "./validate-anatomy-for-publish"; +export * from "./anatomy-rule-paths"; +export * from "./query-anatomy"; +export * from "./match-anatomy-name"; diff --git a/packages/anatomy/src/core/match-anatomy-name.ts b/packages/anatomy/src/core/match-anatomy-name.ts new file mode 100644 index 0000000..24c7f08 --- /dev/null +++ b/packages/anatomy/src/core/match-anatomy-name.ts @@ -0,0 +1,157 @@ +import { Result } from "neverthrow"; +import type { AnatomyEntry, AnatomyBinding, AnatomyBindingFormat } from "@anatomy-cli/schemas"; + +export type BindingScope = Readonly>; + +export type NameMatch = + | { kind: "match"; captures: Record } + | { kind: "binding_format_mismatch"; name: string; value: string; format: AnatomyBindingFormat } + | { kind: "binding_pattern_mismatch"; name: string; value: string; pattern: string } + | { kind: "binding_consistency_mismatch"; name: string; expected: string; actual: string } + | { kind: "none" }; + +type BindingMismatch = Exclude; + +const escapeRegularExpression = (value: string): string => { + return value.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&"); +}; + +const createNamePattern = (entry: AnatomyEntry, ignoreCase = false): RegExp => { + if (entry.name.type === "literal") { + return new RegExp( + `^${escapeRegularExpression(entry.name.value)}$`, + ignoreCase ? "i" : undefined, + ); + } + + const openingBracket = entry.name.value.indexOf("<"); + const closingBracket = entry.name.value.indexOf(">", openingBracket + 1); + const prefix = entry.name.value.slice(0, openingBracket); + const suffix = entry.name.value.slice(closingBracket + 1); + const placeholderExpression = suffix.includes(".") ? "[^./\\\\]+" : "[^/\\\\]+"; + + return new RegExp( + `^${escapeRegularExpression(prefix)}${placeholderExpression}${escapeRegularExpression(suffix)}$`, + ignoreCase ? "i" : undefined, + ); +}; + +const parsePlaceholder = ( + entry: AnatomyEntry, +): { name: string; prefix: string; suffix: string } | undefined => { + if (entry.name.type !== "placeholder") return undefined; + + const openingBracket = entry.name.value.indexOf("<"); + const closingBracket = entry.name.value.indexOf(">", openingBracket + 1); + if (openingBracket < 0 || closingBracket < 0) return undefined; + + return { + name: entry.name.value.slice(openingBracket + 1, closingBracket), + prefix: entry.name.value.slice(0, openingBracket), + suffix: entry.name.value.slice(closingBracket + 1), + }; +}; + +const bindingFormatPatterns: Record = { + PascalCase: /^[A-Z][A-Za-z0-9]*$/, + camelCase: /^[a-z][A-Za-z0-9]*$/, + "kebab-case": /^[a-z0-9]+(?:-[a-z0-9]+)*$/, + snake_case: /^[a-z0-9]+(?:_[a-z0-9]+)*$/, + SCREAMING_SNAKE_CASE: /^[A-Z0-9]+(?:_[A-Z0-9]+)*$/, +}; + +const compilePattern = Result.fromThrowable( + (pattern: string) => new RegExp(`^(?:${pattern})$`), + () => undefined, +); + +const matchesBinding = (binding: AnatomyBinding, value: string): BindingMismatch | undefined => { + if ( + binding.format !== undefined && + (bindingFormatPatterns[binding.format] === undefined || + !bindingFormatPatterns[binding.format].test(value)) + ) { + return { + kind: "binding_format_mismatch", + name: "", + value, + format: binding.format, + }; + } + + if (binding.pattern !== undefined) { + const compiledPattern = compilePattern(binding.pattern); + if (compiledPattern.isErr()) { + return { + kind: "binding_pattern_mismatch", + name: "", + value, + pattern: binding.pattern, + }; + } + + if (!compiledPattern.value.test(value)) { + return { + kind: "binding_pattern_mismatch", + name: "", + value, + pattern: binding.pattern, + }; + } + } + + return undefined; +}; + +export const evaluateName = ( + entry: AnatomyEntry, + actualName: string, + scope: BindingScope, + bindings: Readonly>, + ignoreCase = false, +): NameMatch => { + if (entry.name.type === "literal") { + return createNamePattern(entry, ignoreCase).test(actualName) + ? { kind: "match", captures: {} } + : { kind: "none" }; + } + + const placeholder = parsePlaceholder(entry); + if (!placeholder) return { kind: "none" }; + + const placeholderExpression = placeholder.suffix.includes(".") + ? "[^./\\\\]+" + : "[^/\\\\]+"; + const pattern = new RegExp( + `^${escapeRegularExpression(placeholder.prefix)}(${placeholderExpression})${escapeRegularExpression(placeholder.suffix)}$`, + ignoreCase ? "i" : undefined, + ); + const match = pattern.exec(actualName); + if (!match) return { kind: "none" }; + + const capturedValue = match[1]; + if (capturedValue === undefined) return { kind: "none" }; + + const boundValue = scope[placeholder.name]; + if (boundValue !== undefined && boundValue !== capturedValue) { + return { + kind: "binding_consistency_mismatch", + name: placeholder.name, + expected: boundValue, + actual: capturedValue, + }; + } + + const binding = bindings[placeholder.name]; + if (binding !== undefined) { + const bindingMismatch = matchesBinding(binding, capturedValue); + if (bindingMismatch !== undefined) { + return { ...bindingMismatch, name: placeholder.name }; + } + } + + return { + kind: "match", + captures: boundValue === undefined ? { [placeholder.name]: capturedValue } : {}, + }; +}; diff --git a/packages/anatomy/src/core/query-anatomy.spec.ts b/packages/anatomy/src/core/query-anatomy.spec.ts new file mode 100644 index 0000000..99c6962 --- /dev/null +++ b/packages/anatomy/src/core/query-anatomy.spec.ts @@ -0,0 +1,145 @@ +import { AnatomyDraftInputSchema, AnatomyQueryWithConstraintsSchema } from "@anatomy-cli/schemas"; +import { describe, expect, it } from "vitest"; +import { checkAnatomy } from "./check-anatomy"; +import { queryAnatomy } from "./query-anatomy"; +import { anatomyRulePaths } from "./anatomy-rule-paths"; + +const serviceDefinition = () => AnatomyDraftInputSchema.parse({ + name: "Services", purpose: "Agent workflow", + structure: { + schemaVersion: 1, + defaultPolicies: { missingRequired: "block", unexpectedEntry: "warn", nameMismatch: "block", nestingMismatch: "block" }, + bindings: { Name: { format: "PascalCase", pattern: "[A-Z][a-z]+" } }, + root: { children: [{ + kind: "directory", name: { type: "placeholder", value: "Service" }, + quantity: "one_or_more", policyOverrides: { unexpectedEntry: "block" }, + children: [{ + kind: "one_of", minimumMatches: 1, maximumMatches: 1, + alternatives: ["ts", "js"].map((extension) => ({ + kind: "file", name: { type: "placeholder", value: `Service.${extension}` }, quantity: "exactly_one", + })), + }], + }] }, + }, +}); + +describe("queryAnatomy", () => { + it("describes the root and validates the public response schema", () => { + const result = queryAnatomy(serviceDefinition(), ".")._unsafeUnwrap(); + expect(AnatomyQueryWithConstraintsSchema.safeParse(result).success).toBe(true); + expect(result).toMatchObject({ status: "resolved", path: ".", captures: {} }); + expect(result.rules[0]?.node.kind).toBe("directory"); + }); + + it("resolves a future file with inherited captures, policies and one-of constraints", () => { + const definition = serviceDefinition(); + const result = queryAnatomy(definition, "./UserService/UserService.ts")._unsafeUnwrap(); + expect(result).toMatchObject({ + status: "resolved", captures: { Name: "User" }, policies: { unexpectedEntry: "block" }, + rules: [{ expectedName: "UserService.ts", rulePath: "/structure/root/children/0/children/0/alternatives/0" }], + groups: [{ minimumMatches: 1, maximumMatches: 1 }], + ancestors: [{ name: "UserService", quantity: "one_or_more" }], + }); + const checked = checkAnatomy(definition, [{ kind: "directory", name: "UserService", children: [ + { kind: "file", name: "UserService.ts" }, + ] }])._unsafeUnwrap(); + expect(checked.conforms).toBe(true); + expect(checked.issues).toEqual([]); + }); + + it.each([ + ["userService", "binding_format_mismatch"], + ["User2Service", "binding_pattern_mismatch"], + ["UserService/OrderService.ts", "binding_consistency_mismatch"], + ])("reports the same naming failure as validation for %s", (path, reason) => { + const definition = serviceDefinition(); + const query = queryAnatomy(definition, path)._unsafeUnwrap(); + expect(query).toMatchObject({ status: "mismatch", reason }); + const [directory, file] = path.split("/"); + const checked = checkAnatomy(definition, [{ kind: "directory", name: directory!, children: + file ? [{ kind: "file", name: file }] : [], + }])._unsafeUnwrap(); + expect(checked.issues.some((issue) => issue.code === reason)).toBe(true); + }); + + it("keeps sibling directory bindings independent", () => { + const definition = serviceDefinition(); + expect(queryAnatomy(definition, "UserService/UserService.ts")._unsafeUnwrap().captures).toEqual({ Name: "User" }); + expect(queryAnatomy(definition, "OrderService/OrderService.js")._unsafeUnwrap().captures).toEqual({ Name: "Order" }); + }); + + it("does not treat unmatched descendants as unconstrained success", () => { + const result = queryAnatomy(serviceDefinition(), "UserService/extra/deep.ts")._unsafeUnwrap(); + expect(result).toMatchObject({ status: "unmatched", scopePath: "UserService", policies: { unexpectedEntry: "block" } }); + expect(result.reason).toContain("Descendants are not checked"); + }); + + it("rejects descent through a declared file", () => { + const result = queryAnatomy(serviceDefinition(), "UserService/UserService.ts/child")._unsafeUnwrap(); + expect(result).toMatchObject({ status: "mismatch", reason: "nesting_mismatch" }); + }); + + it("exposes overlapping rules without guessing the consuming rule", () => { + const definition = serviceDefinition(); + const original = definition.structure.root.children[0]!; + definition.structure.root.children.push({ ...original, id: crypto.randomUUID(), + ...(original.kind === "directory" ? { children: [] } : {}), + }); + const query = queryAnatomy(definition, "UserService")._unsafeUnwrap(); + expect(query.status).toBe("ambiguous"); + expect(query.matches).toHaveLength(2); + }); + + it("provides stable rule pointers when parsing generates fresh IDs", () => { + const left = serviceDefinition(); + const right = serviceDefinition(); + expect(left.structure.root.children[0]?.id).not.toBe(right.structure.root.children[0]?.id); + expect(queryAnatomy(left, "UserService")._unsafeUnwrap().matches) + .toEqual(queryAnatomy(right, "UserService")._unsafeUnwrap().matches); + const registry = anatomyRulePaths(left); + const issue = checkAnatomy(left, [])._unsafeUnwrap().issues[0]!; + expect(registry.get(issue.constraintId!)?.rulePath).toBe("/structure/root/children/0"); + }); + + it.each(["../outside", "a/../../b", "/etc", "C:\\code", "\\\\server\\share", "", "a\0b"])("rejects invalid path %j", (path) => { + expect(queryAnatomy(serviceDefinition(), path).isErr()).toBe(true); + }); + + it("normalizes Windows relative paths", () => { + expect(queryAnatomy(serviceDefinition(), "UserService\\UserService.ts")._unsafeUnwrap().status).toBe("resolved"); + }); + + it("preserves angle brackets in literal names even with an inherited binding", () => { + const definition = serviceDefinition(); + const directory = definition.structure.root.children[0]!; + if (directory.kind !== "directory") throw new Error("Expected directory fixture"); + directory.children = [{ + id: crypto.randomUUID(), kind: "file", name: { type: "literal", value: ".txt" }, + quantity: "exactly_one", policyOverrides: {}, + }]; + expect(queryAnatomy(definition, "UserService/.txt")._unsafeUnwrap().rules[0]?.expectedName) + .toBe(".txt"); + }); + + it("returns invalid definitions as errors even for an unmatched path", () => { + const definition = serviceDefinition(); + definition.structure.bindings = { Name: { pattern: "[" } }; + expect(queryAnatomy(definition, "unknown").isErr()).toBe(true); + }); + + it("does not claim a case-only match selects a one-of alternative", () => { + const definition = serviceDefinition(); + const directory = definition.structure.root.children[0]!; + if (directory.kind !== "directory") throw new Error("Expected directory fixture"); + const group = directory.children[0]!; + if (group.kind !== "one_of") throw new Error("Expected one-of fixture"); + group.alternatives[0]!.name = { type: "literal", value: "index.ts" }; + const result = queryAnatomy(definition, "UserService/Index.ts")._unsafeUnwrap(); + expect(result.status).toBe("unmatched"); + expect(result.matches).toEqual([]); + const checked = checkAnatomy(definition, [{ kind: "directory", name: "UserService", children: [ + { kind: "file", name: "Index.ts" }, + ] }])._unsafeUnwrap(); + expect(checked.issues.some((issue) => issue.code === "one_of_mismatch")).toBe(true); + }); +}); diff --git a/packages/anatomy/src/core/query-anatomy.ts b/packages/anatomy/src/core/query-anatomy.ts new file mode 100644 index 0000000..d3d0d67 --- /dev/null +++ b/packages/anatomy/src/core/query-anatomy.ts @@ -0,0 +1,110 @@ +import { err, ok, type Result } from "neverthrow"; +import { AnatomyQueryWithConstraintsSchema, type AnatomyDraftInput, type AnatomyNode, type AnatomyQueryWithConstraints } from "@anatomy-cli/schemas"; +import { evaluateName } from "./match-anatomy-name"; +import { resolveAnatomyPolicies } from "./resolveAnatomyPolicies"; +import { anatomyRulePaths } from "./anatomy-rule-paths"; +import { validateAnatomyForPublish, type AnatomyValidationIssue } from "./validate-anatomy-for-publish"; + +const QueryStatus = AnatomyQueryWithConstraintsSchema.shape.status.enum; + +export class AnatomyQueryPathError extends Error { + constructor(public readonly path: string) { + super(`Query path must be relative to the target, without parent traversal: ${path}`); + this.name = "AnatomyQueryPathError"; + } +} + +export const queryAnatomy = ( + definition: AnatomyDraftInput, + path: string, +): Result => { + const normalized = path.replaceAll("\\", "/"); + if (!path || normalized.startsWith("/") || /^[A-Za-z]:/.test(normalized) || + normalized.split("/").includes("..") || normalized.includes("\0")) { + return err(new AnatomyQueryPathError(path)); + } + const validated = validateAnatomyForPublish(definition); + if (validated.isErr()) return err(validated.error); + + const parts = normalized.split("/").filter((part) => part && part !== "."); + const registry = anatomyRulePaths(definition); + const defaults = definition.structure.defaultPolicies; + const policyAncestors: Parameters[1] = []; + const result: AnatomyQueryWithConstraints = { + contractVersion: 1, operation: "query", path: parts.join("/") || ".", scopePath: ".", + status: QueryStatus.resolved, reason: null, captures: {}, bindings: definition.structure.bindings ?? {}, + policies: defaults, ancestors: [], rules: [], matches: [], groups: [], + }; + const policiesFor = (node?: AnatomyNode) => { + const resolved = resolveAnatomyPolicies(defaults, policyAncestors, + node && node.kind !== "one_of" ? { id: node.id, overrides: node.policyOverrides } : undefined); + return { + missingRequired: resolved.missingRequired.value, + unexpectedEntry: resolved.unexpectedEntry.value, + nameMismatch: resolved.nameMismatch.value, + nestingMismatch: resolved.nestingMismatch.value, + }; + }; + const describe = (nodes: AnatomyNode[]) => nodes.map((node) => ({ + rulePath: registry.get(node.id)!.rulePath, node, policies: policiesFor(node), + expectedName: node.kind === "one_of" ? null : node.name.type === "literal" ? node.name.value : node.name.value.replace( + /<([^<>]+)>/, (placeholder, name: string) => result.captures[name] ?? placeholder, + ), + })); + let nodes = definition.structure.root.children; + result.rules = describe(nodes); + + for (const [index, part] of parts.entries()) { + result.policies = policiesFor(); + result.rules = describe(nodes); + const entries = nodes.flatMap((node) => node.kind === "one_of" + ? node.alternatives.map((entry) => ({ node: entry, inGroup: true })) + : [{ node, inGroup: false }]); + const candidates = entries.flatMap(({ node, inGroup }) => { + const exact = evaluateName(node, part, result.captures, result.bindings); + const match = exact.kind === "none" && !inGroup + ? evaluateName(node, part, result.captures, result.bindings, true) : exact; + return match.kind === "none" ? [] : [{ node, match, caseMismatch: exact.kind === "none" }]; + }); + result.matches = candidates.map(({ node }) => registry.get(node.id)!.rulePath); + if (candidates.length !== 1) { + result.status = candidates.length === 0 ? QueryStatus.unmatched : QueryStatus.ambiguous; + result.reason = candidates.length === 0 + ? `No declared entry matches "${part}" under ${result.scopePath}; the parent's unexpectedEntry policy still applies. Descendants are not checked.` + : `Multiple rules may consume "${part}"; rule order, entry kind and sibling entries affect validation. Inspect the candidates before editing.`; + return ok(result); + } + const candidate = candidates[0]!; + const { node, match } = candidate; + if (match.kind !== "match" || candidate.caseMismatch || + (index < parts.length - 1 && node.kind !== "directory")) { + result.status = QueryStatus.mismatch; + result.reason = candidate.caseMismatch ? "name_mismatch" + : match.kind !== "match" ? match.kind : "nesting_mismatch"; + return ok(result); + } + for (const group of nodes) { + if (group.kind === "one_of" && group.alternatives.some((entry) => entry.id === node.id)) { + result.groups.push({ + rulePath: registry.get(group.id)!.rulePath, + minimumMatches: group.minimumMatches, maximumMatches: group.maximumMatches, + alternatives: group.alternatives.map((entry) => registry.get(entry.id)!.rulePath), + }); + } + } + result.captures = { ...result.captures, ...match.captures }; + result.rules = describe([node]); + result.policies = policiesFor(node); + if (index === parts.length - 1) return ok(result); + if (node.kind === "directory") { + result.ancestors.push({ + rulePath: registry.get(node.id)!.rulePath, name: part, + quantity: node.quantity, policies: result.policies, + }); + policyAncestors.push({ id: node.id, overrides: node.policyOverrides }); + result.scopePath = parts.slice(0, index + 1).join("/"); + nodes = node.children; + } + } + return ok(result); +}; diff --git a/packages/schemas/src/anatomy/AnatomyBinding.schema.ts b/packages/schemas/src/anatomy/AnatomyBinding.schema.ts index 840dc8a..ee09c1c 100644 --- a/packages/schemas/src/anatomy/AnatomyBinding.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyBinding.schema.ts @@ -10,7 +10,7 @@ const compilePattern = Result.fromThrowable( /** Constraints applied to values captured by a named Anatomy placeholder. */ export const AnatomyBindingSchema = z - .object({ + .strictObject({ /** Optional built-in naming convention. */ format: AnatomyBindingFormatSchema.optional(), /** Optional JavaScript regular expression, evaluated as a full match. */ diff --git a/packages/schemas/src/anatomy/AnatomyCheckWithDiagnosticsSchema.ts b/packages/schemas/src/anatomy/AnatomyCheckWithDiagnosticsSchema.ts new file mode 100644 index 0000000..6f4f062 --- /dev/null +++ b/packages/schemas/src/anatomy/AnatomyCheckWithDiagnosticsSchema.ts @@ -0,0 +1,25 @@ +import { z } from "zod/v4"; +import { AnatomyNodeSchema } from "./AnatomyNode.schema"; +import { AnatomyPolicyValueSchema } from "./AnatomyPolicyValue.schema"; + +export const AnatomyCheckWithDiagnosticsSchema = z.object({ + contractVersion: z.literal(1), + operation: z.literal("check"), + conforms: z.boolean(), + summary: z.object({ block: z.number(), warn: z.number(), allow: z.number() }), + issues: z.array(z.object({ + code: z.string(), + severity: AnatomyPolicyValueSchema, + path: z.string(), + constraintId: z.string().nullable(), + message: z.string(), + rulePath: z.string().nullable(), + expected: AnatomyNodeSchema.nullable(), + actual: z.array(z.object({ kind: z.enum(["file", "directory"]), name: z.string() })), + })), + definition: z.object({ path: z.string(), name: z.string(), schemaVersion: z.literal(1) }), + targetPath: z.string(), + ignoredNames: z.array(z.string()), +}); + +export type AnatomyCheckWithDiagnostics = z.infer; diff --git a/packages/schemas/src/anatomy/AnatomyContract.spec.ts b/packages/schemas/src/anatomy/AnatomyContract.spec.ts new file mode 100644 index 0000000..39b9475 --- /dev/null +++ b/packages/schemas/src/anatomy/AnatomyContract.spec.ts @@ -0,0 +1,38 @@ +import { describe, expect, it } from "vitest"; +import { AnatomyDraftInputSchema } from "./AnatomyDraftInput.schema"; + +const definition = () => ({ + name: "Contract", purpose: "Reject unsupported rules", + structure: { + schemaVersion: 1, + defaultPolicies: { missingRequired: "block", unexpectedEntry: "warn", nameMismatch: "warn", nestingMismatch: "block" }, + root: { children: [{ kind: "file", name: { type: "literal", value: "index.ts" }, quantity: "exactly_one" }] }, + }, +}); + +describe("Anatomy definition compatibility", () => { + it("accepts version one with omitted IDs and overrides", () => { + expect(AnatomyDraftInputSchema.safeParse(definition()).success).toBe(true); + }); + it("rejects unsupported versions and node kinds", () => { + const input = definition(); + input.structure.schemaVersion = 2; + expect(AnatomyDraftInputSchema.safeParse(input).success).toBe(false); + input.structure.schemaVersion = 1; + input.structure.root.children[0]!.kind = "dependency"; + expect(AnatomyDraftInputSchema.safeParse(input).success).toBe(false); + }); + it.each(["structure", "root", "node", "name", "policies", "overrides", "binding"])("rejects unknown %s rules instead of silently stripping them", (location) => { + const input = definition(); + const node = input.structure.root.children[0]!; + const target = location === "structure" ? input.structure + : location === "root" ? input.structure.root + : location === "node" ? node + : location === "name" ? node.name + : location === "policies" ? input.structure.defaultPolicies : null; + if (target) Object.assign(target, { unsupportedRule: true }); + if (location === "overrides") Object.assign(node, { policyOverrides: { unsupportedRule: "block" } }); + if (location === "binding") Object.assign(input.structure, { bindings: { Name: { format: "PascalCase", unsupportedRule: true } } }); + expect(AnatomyDraftInputSchema.safeParse(input).success).toBe(false); + }); +}); diff --git a/packages/schemas/src/anatomy/AnatomyDraftInput.schema.ts b/packages/schemas/src/anatomy/AnatomyDraftInput.schema.ts index 0feaa8e..1b591cb 100644 --- a/packages/schemas/src/anatomy/AnatomyDraftInput.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyDraftInput.schema.ts @@ -3,7 +3,7 @@ import { z } from "zod/v4"; import { AnatomyStructureSchema } from "./AnatomyStructure.schema"; /** Author-managed definition used to create or replace an Anatomy draft. */ -export const AnatomyDraftInputSchema = z.object({ +export const AnatomyDraftInputSchema = z.strictObject({ /** Anatomy name displayed to users. */ name: z.string().trim().min(1).max(120), /** Problem addressed by the structure contract and its intended purpose. */ diff --git a/packages/schemas/src/anatomy/AnatomyFileEntry.schema.ts b/packages/schemas/src/anatomy/AnatomyFileEntry.schema.ts index d7fa1a4..ddb760f 100644 --- a/packages/schemas/src/anatomy/AnatomyFileEntry.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyFileEntry.schema.ts @@ -5,7 +5,7 @@ import { AnatomyPolicyOverridesSchema } from "./AnatomyPolicyOverrides.schema"; import { AnatomyQuantitySchema } from "./AnatomyQuantity.schema"; /** File requirement with naming, quantity, and policy constraints. */ -export const AnatomyFileEntrySchema = z.object({ +export const AnatomyFileEntrySchema = z.strictObject({ /** Unique file-entry identifier, generated during schema parsing when omitted. */ id: z.string().uuid().default(() => crypto.randomUUID()), /** Literal filename or placeholder expression. */ diff --git a/packages/schemas/src/anatomy/AnatomyNameExpression.schema.ts b/packages/schemas/src/anatomy/AnatomyNameExpression.schema.ts index a6b4527..ca7c48a 100644 --- a/packages/schemas/src/anatomy/AnatomyNameExpression.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyNameExpression.schema.ts @@ -2,13 +2,13 @@ import { z } from "zod/v4"; /** Literal or placeholder matching expression for an Anatomy entry name. */ export const AnatomyNameExpressionSchema = z.discriminatedUnion("type", [ - z.object({ + z.strictObject({ /** Expression type that requires an exact literal-name match. */ type: z.literal("literal"), /** Literal filename that must match. */ value: z.string().trim().min(1), }), - z.object({ + z.strictObject({ /** Expression type that matches a semantic placeholder. */ type: z.literal("placeholder"), /** Placeholder expression describing the permitted name. */ diff --git a/packages/schemas/src/anatomy/AnatomyOneOfGroup.schema.ts b/packages/schemas/src/anatomy/AnatomyOneOfGroup.schema.ts index 4040b9e..cdd26e3 100644 --- a/packages/schemas/src/anatomy/AnatomyOneOfGroup.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyOneOfGroup.schema.ts @@ -9,7 +9,7 @@ export const AnatomyOneOfGroupSchema: z.ZodType<{ minimumMatches: number; maximumMatches: number; alternatives: AnatomyEntry[]; -}> = z.object({ +}> = z.strictObject({ /** Unique group identifier, generated during schema parsing when omitted. */ id: z.string().uuid().default(() => crypto.randomUUID()), /** Node discriminant, fixed to one_of. */ diff --git a/packages/schemas/src/anatomy/AnatomyPolicy.schema.ts b/packages/schemas/src/anatomy/AnatomyPolicy.schema.ts index 80973a8..027f4e4 100644 --- a/packages/schemas/src/anatomy/AnatomyPolicy.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyPolicy.schema.ts @@ -2,7 +2,7 @@ import { z } from "zod/v4"; import { AnatomyPolicyValueSchema } from "./AnatomyPolicyValue.schema"; /** Default policies applied when a Crate does not conform to an Anatomy. */ -export const AnatomyPoliciesSchema = z.object({ +export const AnatomyPoliciesSchema = z.strictObject({ /** Default action when a required entry is missing. */ missingRequired: AnatomyPolicyValueSchema, /** Default action when an undeclared entry is present. */ diff --git a/packages/schemas/src/anatomy/AnatomyPolicyOverrides.schema.ts b/packages/schemas/src/anatomy/AnatomyPolicyOverrides.schema.ts index 21114cc..93b5d2b 100644 --- a/packages/schemas/src/anatomy/AnatomyPolicyOverrides.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyPolicyOverrides.schema.ts @@ -2,7 +2,7 @@ import { z } from "zod/v4"; /** Local overrides of the default Anatomy policies for one structure entry. */ export const AnatomyPolicyOverridesSchema = z - .object({ + .strictObject({ /** Local action when a required entry is missing. */ missingRequired: z.enum(["block", "warn", "allow"]), /** Local action when an undeclared entry is present. */ diff --git a/packages/schemas/src/anatomy/AnatomyQueryWithConstraintsSchema.ts b/packages/schemas/src/anatomy/AnatomyQueryWithConstraintsSchema.ts new file mode 100644 index 0000000..7a5c5c7 --- /dev/null +++ b/packages/schemas/src/anatomy/AnatomyQueryWithConstraintsSchema.ts @@ -0,0 +1,38 @@ +import { z } from "zod/v4"; +import { AnatomyNodeSchema } from "./AnatomyNode.schema"; +import { AnatomyPoliciesSchema } from "./AnatomyPolicy.schema"; +import { AnatomyBindingSchema } from "./AnatomyBinding.schema"; +import { AnatomyQuantitySchema } from "./AnatomyQuantity.schema"; + +export const AnatomyQueryWithConstraintsSchema = z.object({ + contractVersion: z.literal(1), + operation: z.literal("query"), + path: z.string(), + scopePath: z.string(), + status: z.enum(["resolved", "unmatched", "ambiguous", "mismatch"]), + reason: z.string().nullable(), + captures: z.record(z.string(), z.string()), + bindings: z.record(z.string(), AnatomyBindingSchema), + policies: AnatomyPoliciesSchema, + ancestors: z.array(z.object({ + rulePath: z.string(), + name: z.string(), + quantity: AnatomyQuantitySchema, + policies: AnatomyPoliciesSchema, + })), + rules: z.array(z.object({ + rulePath: z.string(), + node: AnatomyNodeSchema, + expectedName: z.string().nullable(), + policies: AnatomyPoliciesSchema, + })), + matches: z.array(z.string()), + groups: z.array(z.object({ + rulePath: z.string(), + minimumMatches: z.number(), + maximumMatches: z.number(), + alternatives: z.array(z.string()), + })), +}); + +export type AnatomyQueryWithConstraints = z.infer; diff --git a/packages/schemas/src/anatomy/AnatomyStructure.schema.ts b/packages/schemas/src/anatomy/AnatomyStructure.schema.ts index 664a7ee..eb41afe 100644 --- a/packages/schemas/src/anatomy/AnatomyStructure.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyStructure.schema.ts @@ -5,7 +5,7 @@ import { AnatomyNodeSchema } from "./AnatomyNode.schema"; import { AnatomyBindingSchema } from "./AnatomyBinding.schema"; /** Recursive filesystem structure contract that an Anatomy must satisfy. */ -export const AnatomyStructureSchema = z.object({ +export const AnatomyStructureSchema = z.strictObject({ /** Structure document format version used for future-compatible migrations. */ schemaVersion: z.literal(1), /** Default policies used by nodes that do not provide local overrides. */ @@ -20,7 +20,7 @@ export const AnatomyStructureSchema = z.object({ ) .optional(), /** Virtual root node that does not represent a real directory. */ - root: z.object({ + root: z.strictObject({ /** Structure nodes at the top level of the Anatomy. */ children: z.array(AnatomyNodeSchema), }), diff --git a/packages/schemas/src/anatomy/index.ts b/packages/schemas/src/anatomy/index.ts index 85fc306..77897e1 100644 --- a/packages/schemas/src/anatomy/index.ts +++ b/packages/schemas/src/anatomy/index.ts @@ -21,3 +21,5 @@ export * from "./AnatomyStatus.schema"; export * from "./AnatomyStructure.schema"; export * from "./AnatomySummary.schema"; export * from "./AnatomyVersion.schema"; +export * from "./AnatomyQueryWithConstraintsSchema"; +export * from "./AnatomyCheckWithDiagnosticsSchema"; From 5b300ae811561ac11e32873dd7f73ffe711c3e00 Mon Sep 17 00:00:00 2001 From: Zander Zhang <276678881@qq.com> Date: Tue, 8 Sep 2026 00:06:39 +0800 Subject: [PATCH 2/8] feat: enforce named function export contracts --- README.md | 51 +++++- README.zh-CN.md | 25 ++- .../anatomies/cli-source.anatomy.json | 22 +++ .../src/analyze-source-exports.spec.ts | 74 ++++++++ .../anatomy-cli/src/analyze-source-exports.ts | 162 ++++++++++++++++++ apps/anatomy-cli/src/cli.ts | 12 +- .../anatomy-cli/src/collect-source-exports.ts | 24 +++ .../src/format-agent-result.spec.ts | 11 ++ apps/anatomy-cli/src/format-agent-result.ts | 5 +- .../src/function-export-workflow.spec.ts | 98 +++++++++++ apps/anatomy-cli/src/index.ts | 2 + apps/anatomy-cli/src/source-contract.spec.ts | 12 +- .../anatomy/src/core/anatomy-export-name.ts | 11 ++ packages/anatomy/src/core/check-anatomy.ts | 65 ++++++- .../anatomy/src/core/function-export.spec.ts | 100 +++++++++++ packages/anatomy/src/core/index.ts | 1 + packages/anatomy/src/core/query-anatomy.ts | 16 +- .../src/core/validate-anatomy-for-publish.ts | 22 ++- .../AnatomyCheckWithDiagnosticsSchema.ts | 3 + .../src/anatomy/AnatomyContract.spec.ts | 14 ++ .../anatomy/AnatomyDirectoryEntry.schema.ts | 4 +- .../src/anatomy/AnatomyFileEntry.schema.ts | 2 + .../AnatomyFunctionExportCheckSchema.ts | 11 ++ .../AnatomyFunctionExportRuleSchema.ts | 10 ++ .../AnatomyQueryWithConstraintsSchema.ts | 1 + .../src/anatomy/AnatomySourceExportsSchema.ts | 8 + packages/schemas/src/anatomy/index.ts | 3 + 27 files changed, 746 insertions(+), 23 deletions(-) create mode 100644 apps/anatomy-cli/src/analyze-source-exports.spec.ts create mode 100644 apps/anatomy-cli/src/analyze-source-exports.ts create mode 100644 apps/anatomy-cli/src/collect-source-exports.ts create mode 100644 apps/anatomy-cli/src/function-export-workflow.spec.ts create mode 100644 packages/anatomy/src/core/anatomy-export-name.ts create mode 100644 packages/anatomy/src/core/function-export.spec.ts create mode 100644 packages/schemas/src/anatomy/AnatomyFunctionExportCheckSchema.ts create mode 100644 packages/schemas/src/anatomy/AnatomyFunctionExportRuleSchema.ts create mode 100644 packages/schemas/src/anatomy/AnatomySourceExportsSchema.ts diff --git a/README.md b/README.md index 614cebb..aeae79c 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ the tree/checking engine becomes `packages/anatomy`, and only its Anatomy schema closure is kept in `packages/schemas`. Internal Daedalus workspace aliases are replaced with the standalone `@anatomy-cli/*` scope. -The implementation is intentionally based on a structured file tree, not on ad-hoc source inspection: +Structural rules use a deterministic file tree. Optional function-export rules add AST analysis for selected JavaScript and TypeScript files: ```text JSON Anatomy Draft @@ -26,6 +26,8 @@ deterministic filesystem tree ↓ name / nesting / quantity / one-of checks ↓ +optional function-export checks + ↓ block · warn · allow result ``` @@ -195,6 +197,53 @@ The supported built-ins are `PascalCase`, `camelCase`, `kebab-case`, when `^` and `$` are omitted. A placeholder captured by a directory is reused by matching descendants; each repeated directory gets its own captured value. +## Function exports (source checkout) + +File rules can opt into source-level export checks. For example, this file node +requires `getUser.ts` to have exactly one runtime export: a named function called +`getUser`. + +```json +{ + "kind": "file", + "name": { "type": "placeholder", "value": ".ts" }, + "quantity": "one_or_more", + "exports": { "name": "file_stem" } +} +``` + +`file_stem` removes only the last extension. For `.method.ts`, use +`"exports": { "name": { "type": "placeholder", "value": "" } }` instead. +Export placeholders must already be captured by the file name or an ancestor +directory; they cannot introduce an unrelated binding. Literal export names are +also supported through `{"type":"literal","value":"getUser"}`. The export +rule's `policy` defaults to `block`; it is independent of structural policies. + +Named function declarations, async/generator functions, arrow functions and +function expressions are supported, including local `export { implementation as +getUser }` aliases. The exported public name is checked. Type aliases, interfaces +and type-only exports do not count. Default exports, missing exports, additional +runtime exports and non-function exports violate the rule. Imports/re-exports or +computed wrappers whose callable nature cannot be determined locally, declaration +files, CommonJS export mutations and syntax errors produce operational errors +(exit `2`). The source is parsed, never imported or executed. This is a static +export-declaration check, not a proof of runtime behavior or type correctness. + +Only matched files with an `exports` rule are read for source analysis; existing +structural-only definitions keep their behavior. Query mode reports `expectedExport` +and shows the requirement in human output without analyzing source. Check JSON +includes `expectedExport`, `actualExports`, and the existing `rulePath` on export +findings, with codes `export_count_mismatch`, `export_name_mismatch` or +`export_kind_mismatch`. Run the same `anatomy` check command after editing the +file's contents; no extra CLI flag is needed. + +The pure engine's `planAnatomyCheck` returns `structuralResult` and `exportChecks`. +That plan is not a complete conformance result. Call `checkAnatomy` with the analyzed +exports map keyed by relative file path to enforce both structure and exports; +it returns `AnatomySourceAnalysisError` if required analysis is absent. The CLI +performs both steps automatically. The bundled CLI now includes the TypeScript +parser; this feature needs a new CLI release before registry installs support it. + ## Agent workflow (source checkout) Query the definition before editing, then check the resulting file tree. These diff --git a/README.zh-CN.md b/README.zh-CN.md index a254131..fd6a85d 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -13,7 +13,7 @@ 迁移保留了原有模块边界:Daedalus CLI 成为应用,树操作与检查引擎归入 `packages/anatomy`,`packages/schemas` 仅保留 Anatomy Schema 及其依赖。Daedalus 内部工作区别名已替换为独立的 `@anatomy-cli/*` 作用域。 -实现基于结构化文件树,不依赖临时编写的源码扫描规则: +结构规则使用确定性的文件树;可选的函数导出规则会对选中的 JavaScript / TypeScript 文件进行 AST 分析: ```text JSON Anatomy Draft @@ -22,6 +22,8 @@ deterministic filesystem tree ↓ name / nesting / quantity / one-of checks ↓ +optional function-export checks + ↓ block · warn · allow result ``` @@ -164,6 +166,27 @@ Anatomy JSON 定义只需包含供人阅读的元数据和结构约束。可以 目录捕获的占位符值会被匹配到的后代节点复用;每个重复目录都有各自独立的捕获值。 +## 函数导出约束(源码运行) + +文件规则可以显式开启源码导出检查。例如下面的文件节点要求 `getUser.ts` 只能有一个运行时导出,而且必须是名为 `getUser` 的具名函数: + +```json +{ + "kind": "file", + "name": { "type": "placeholder", "value": ".ts" }, + "quantity": "one_or_more", + "exports": { "name": "file_stem" } +} +``` + +`file_stem` 仅去掉最后一个扩展名。如果文件规则是 `.method.ts`,改用 `"exports": { "name": { "type": "placeholder", "value": "" } }`。导出名的占位符必须已经由文件名或祖先目录捕获,不能另起一个无关绑定;也可使用 `{"type":"literal","value":"getUser"}` 明确指定导出名。导出规则的 `policy` 默认是 `block`,独立于结构策略。 + +支持具名函数声明、async/generator 函数、箭头函数和函数表达式,也支持本地 `export { implementation as getUser }`,检查的是对外导出的名称。类型别名、接口和纯类型导出不计入数量。默认导出、没有导出、多余运行时导出、导出非函数值都会违反规则。无法在本文件确定函数性质的导入/转导出和动态包装、声明文件、CommonJS 导出修改、语法错误返回运行错误(退出码 `2`)。源码只解析,不导入、不执行;这属于静态导出声明检查,不证明运行时行为和类型正确。 + +仅对匹配且声明了 `exports` 的文件读取源码,原有纯结构定义保持行为。查询模式返回 `expectedExport`,并在人类可读输出中展示要求,不分析源码。检查的导出诊断包含 `expectedExport`、`actualExports` 和原有 `rulePath`,错误码为 `export_count_mismatch`、`export_name_mismatch`、`export_kind_mismatch`。修改文件内容后重新运行同一条 `anatomy` 检查命令即可,无需额外开关。 + +纯引擎的 `planAnatomyCheck` 返回 `structuralResult` 和待分析的 `exportChecks`,规划结果不代表完整验证通过。调用 `checkAnatomy` 时传入以相对文件路径为键的导出分析 Map,才能同时执行结构与导出检查;缺少必要分析时返回 `AnatomySourceAnalysisError`。CLI 自动完成这两个步骤。CLI 构建产物已包含 TypeScript 解析器,这项能力需要后续发布新版后才能通过包管理器安装使用。 + ## Agent 工作流(源码运行) 修改前查询定义,修改后检查文件树。以下命令使用当前源码;查询接口需要后续发布新版 CLI 才能通过包管理器安装使用。 diff --git a/apps/anatomy-cli/anatomies/cli-source.anatomy.json b/apps/anatomy-cli/anatomies/cli-source.anatomy.json index 5e2fedd..254843f 100644 --- a/apps/anatomy-cli/anatomies/cli-source.anatomy.json +++ b/apps/anatomy-cli/anatomies/cli-source.anatomy.json @@ -100,6 +100,28 @@ "kind": "file", "name": { "type": "literal", "value": "install.ts" }, "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "analyze-source-exports.ts" }, + "quantity": "exactly_one", + "exports": { "name": { "type": "literal", "value": "analyzeSourceExports" } } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "collect-source-exports.ts" }, + "quantity": "exactly_one", + "exports": { "name": { "type": "literal", "value": "collectSourceExports" } } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "analyze-source-exports.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "function-export-workflow.spec.ts" }, + "quantity": "exactly_one" } ] } diff --git a/apps/anatomy-cli/src/analyze-source-exports.spec.ts b/apps/anatomy-cli/src/analyze-source-exports.spec.ts new file mode 100644 index 0000000..2e22d9a --- /dev/null +++ b/apps/anatomy-cli/src/analyze-source-exports.spec.ts @@ -0,0 +1,74 @@ +import { describe, expect, it } from "vitest"; +import { analyzeSourceExports } from "./analyze-source-exports"; + +describe("JavaScript and TypeScript export analysis", () => { + it.each([ + "export function getUser() {}", + "export async function getUser() {}", + "export function* getUser() { yield 1; }", + "export const getUser = () => ({});", + "export const getUser = async () => ({});", + "export const getUser = function internal() {};", + "const getUser = () => {}; export { getUser };", + "function implementation() {} export { implementation as getUser };", + "function implementation() {} const getUser = implementation; export { getUser };", + "export const getUser = (() => {}) satisfies () => void;", + "export function getUser(id: string): void; export function getUser(id: number): void; export function getUser(id: string | number) {}", + "export type User = { id: string }; export interface Options {} export function getUser() {}", + "type User = {}; interface Options {} export { User, Options }; export const getUser = () => {};", + "import type { User } from './user'; export { User }; export function getUser() {}", + "export type * from './types'; export function getUser() {}", + "export { type User } from './types'; export function getUser() {}", + "// export function fake() {}\nconst text = 'export const fake = 1'; export function getUser() {}", + "throw new Error('This source must never execute'); export function getUser() {}", + ])("finds local functions without executing source: %s", (source) => { + expect(analyzeSourceExports("/project/getUser.ts", source)._unsafeUnwrap()) + .toEqual([{ name: "getUser", kind: "function" }]); + }); + + it.each(["ts", "tsx", "js", "jsx", "mts", "mjs", "cts", "cjs"])("parses the %s implementation extension", (extension) => { + expect(analyzeSourceExports(`/project/getUser.${extension}`, "export const getUser = () => {};").isOk()).toBe(true); + }); + + it("parses JSX function bodies", () => { + expect(analyzeSourceExports("/project/GetUser.tsx", "export const GetUser = () =>
User
;")._unsafeUnwrap()) + .toEqual([{ name: "GetUser", kind: "function" }]); + }); + + it.each([ + ["export default function getUser() {}", "function"], + ["export default () => {};", "function"], + ["function getUser() {} export { getUser as default };", "function"], + ["export default class User {}", "value"], + ])("preserves default export identity: %s", (source, kind) => { + expect(analyzeSourceExports("/project/getUser.ts", source)._unsafeUnwrap()) + .toEqual([{ name: "default", kind }]); + }); + + it("counts extra runtime values while ignoring type exports", () => { + expect(analyzeSourceExports("/project/getUser.ts", "export const version = 1; export class User {} export type Id = string; export function getUser() {}")._unsafeUnwrap()) + .toEqual([{ name: "version", kind: "value" }, { name: "User", kind: "value" }, { name: "getUser", kind: "function" }]); + }); + + it.each([ + "export function getUser( {", + "export * from './other';", + "export { getUser } from './other';", + "import { getUser } from './other'; export { getUser };", + "export const getUser = createFunction();", + "export declare function getUser(): void;", + "const one = two; const two = one; export { one };", + "export function getUser() {} module.exports = {};", + "export function getUser() {} exports.extra = 1;", + "export function getUser() {} Object.assign(module.exports, { extra: 1 });", + "export = function getUser() {};", + "export const {getUser} = something;", + "export function getUser() {} export function getUser() {}", + ])("does not silently accept unsupported or invalid source: %s", (source) => { + expect(analyzeSourceExports("/project/getUser.ts", source).isErr()).toBe(true); + }); + + it.each(["getUser.d.ts", "getUser.d.mts", "getUser.json"])("rejects unsupported file %s", (filename) => { + expect(analyzeSourceExports(`/project/${filename}`, "export function getUser() {}").isErr()).toBe(true); + }); +}); diff --git a/apps/anatomy-cli/src/analyze-source-exports.ts b/apps/anatomy-cli/src/analyze-source-exports.ts new file mode 100644 index 0000000..087afe3 --- /dev/null +++ b/apps/anatomy-cli/src/analyze-source-exports.ts @@ -0,0 +1,162 @@ +import ts from "typescript"; +import { err, ok, Result, type Result as ResultType } from "neverthrow"; +import { AnatomySourceAnalysisError } from "@anatomy-cli/anatomy/core"; +import type { AnatomySourceExports } from "@anatomy-cli/schemas"; + +const hasModifier = (node: ts.Node, kind: ts.SyntaxKind) => + ts.canHaveModifiers(node) && ts.getModifiers(node)?.some((modifier) => modifier.kind === kind) === true; + +export const analyzeSourceExports = ( + path: string, + content: string, +): ResultType => { + const fail = (message: string) => err(new AnatomySourceAnalysisError(path, `${path}: ${message}`)); + if (!/\.(?:[cm]?[jt]s|[jt]sx)$/i.test(path) || /\.d\.[cm]?ts$/i.test(path)) { + return fail("Function export checks require a JavaScript or TypeScript implementation file"); + } + const parsed = Result.fromThrowable(() => { + const options: ts.CompilerOptions = { noLib: true, noResolve: true, types: [], allowJs: true, target: ts.ScriptTarget.Latest }; + const host = ts.createCompilerHost(options); + host.getSourceFile = (filename, languageVersion) => filename === path + ? ts.createSourceFile(filename, content, languageVersion, true) : undefined; + host.fileExists = (filename) => filename === path; + host.readFile = (filename) => filename === path ? content : undefined; + const program = ts.createProgram([path], options, host); + return { file: program.getSourceFile(path), diagnostics: program.getSyntacticDiagnostics() }; + }, (cause) => new AnatomySourceAnalysisError(path, `Unable to parse ${path}: ${String(cause)}`))(); + if (parsed.isErr()) return err(parsed.error); + const { file, diagnostics } = parsed.value; + if (!file) return fail("Unable to create source file"); + if (diagnostics.length) return fail(ts.flattenDiagnosticMessageText(diagnostics[0]!.messageText, "\n")); + + const locals = new Map(); + const register = (name: string, node: ts.Node) => locals.set(name, [...locals.get(name) ?? [], node]); + const bindingNames = (name: ts.BindingName): string[] => ts.isIdentifier(name) + ? [name.text] : name.elements.flatMap((element) => ts.isOmittedExpression(element) ? [] : bindingNames(element.name)); + for (const statement of file.statements) { + if (ts.isVariableStatement(statement)) { + for (const declaration of statement.declarationList.declarations) { + for (const name of bindingNames(declaration.name)) register(name, declaration); + } + } else if (ts.isImportDeclaration(statement)) { + const clause = statement.importClause; + if (clause?.name) register(clause.name.text, clause); + if (clause?.namedBindings) { + if (ts.isNamespaceImport(clause.namedBindings)) register(clause.namedBindings.name.text, clause); + else for (const specifier of clause.namedBindings.elements) register(specifier.name.text, specifier); + } + } else if ("name" in statement && statement.name && ts.isIdentifier(statement.name as ts.Node)) { + register((statement.name as ts.Identifier).text, statement); + } + } + + const resolveExpression = (expression: ts.Expression, seen: Set): "function" | "value" | "unknown" => { + if (ts.isArrowFunction(expression) || ts.isFunctionExpression(expression)) return "function"; + if (ts.isParenthesizedExpression(expression) || ts.isAsExpression(expression) || + ts.isTypeAssertionExpression(expression) || ts.isSatisfiesExpression(expression) || ts.isNonNullExpression(expression)) { + return resolveExpression(expression.expression, seen); + } + if (ts.isIdentifier(expression)) { + const kind = resolveLocal(expression.text, seen); + return kind === "type" ? "unknown" : kind; + } + if (ts.isCallExpression(expression) || ts.isAwaitExpression(expression) || ts.isPropertyAccessExpression(expression) || + ts.isElementAccessExpression(expression) || ts.isConditionalExpression(expression)) return "unknown"; + return "value"; + }; + const resolveLocal = (name: string, seen = new Set()): "function" | "value" | "type" | "unknown" => { + if (seen.has(name)) return "unknown"; + const declarations = locals.get(name); + if (!declarations?.length) return "unknown"; + const next = new Set([...seen, name]); + const runtime = declarations.filter((node) => !ts.isInterfaceDeclaration(node) && !ts.isTypeAliasDeclaration(node)); + if (!runtime.length) return "type"; + const functions = runtime.filter(ts.isFunctionDeclaration); + if (functions.length === runtime.length) return functions.filter((node) => node.body).length === 1 ? "function" : "unknown"; + if (runtime.length !== 1) return "unknown"; + const node = runtime[0]!; + if (ts.isImportClause(node)) return node.isTypeOnly ? "type" : "unknown"; + if (ts.isImportSpecifier(node)) return node.isTypeOnly || node.parent.parent.isTypeOnly ? "type" : "unknown"; + if (hasModifier(node, ts.SyntaxKind.DeclareKeyword)) return "unknown"; + if (ts.isVariableDeclaration(node)) { + if (!ts.isIdentifier(node.name) || !node.initializer) return "unknown"; + return resolveExpression(node.initializer, next); + } + return "value"; + }; + + let commonJs = false; + const isCommonJsTarget = (node: ts.Node): boolean => { + if (ts.isIdentifier(node)) return node.text === "exports"; + if (ts.isPropertyAccessExpression(node)) return isCommonJsTarget(node.expression) || + (ts.isIdentifier(node.expression) && node.expression.text === "module" && node.name.text === "exports"); + if (ts.isElementAccessExpression(node)) return isCommonJsTarget(node.expression) || + (ts.isIdentifier(node.expression) && node.expression.text === "module" && ts.isStringLiteral(node.argumentExpression) && node.argumentExpression.text === "exports"); + return false; + }; + const inspect = (node: ts.Node): void => { + if (ts.isBinaryExpression(node) && node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && + node.operatorToken.kind <= ts.SyntaxKind.LastAssignment && isCommonJsTarget(node.left)) commonJs = true; + if (ts.isCallExpression(node) && node.arguments.some(isCommonJsTarget)) commonJs = true; + ts.forEachChild(node, inspect); + }; + inspect(file); + if (commonJs) return fail("CommonJS export mutations are not supported; use local ES module exports"); + + const exported: AnatomySourceExports = []; + const exportedFunctions = new Set(); + const addLocal = (local: string, name: string): ResultType => { + const kind = resolveLocal(local); + if (kind === "unknown") return fail(`Cannot determine whether export "${name}" is a local function; imported, ambient and computed exports are not supported`); + if (kind !== "type") exported.push({ name, kind }); + return ok(undefined); + }; + + for (const statement of file.statements) { + if (ts.isExportDeclaration(statement)) { + if (statement.isTypeOnly) continue; + if (statement.moduleSpecifier) { + if (statement.exportClause && ts.isNamedExports(statement.exportClause) && statement.exportClause.elements.every((item) => item.isTypeOnly)) continue; + return fail("Runtime re-exports are not supported; export a local function"); + } + if (!statement.exportClause || !ts.isNamedExports(statement.exportClause)) return fail("Unsupported export declaration"); + for (const item of statement.exportClause.elements) { + if (item.isTypeOnly) continue; + const added = addLocal((item.propertyName ?? item.name).text, item.name.text); + if (added.isErr()) return err(added.error); + } + continue; + } + if (ts.isExportAssignment(statement)) { + if (statement.isExportEquals) return fail("CommonJS export assignments are not supported"); + const kind = resolveExpression(statement.expression, new Set()); + if (kind === "unknown") return fail("Cannot resolve computed default export"); + exported.push({ name: "default", kind }); + continue; + } + if (!hasModifier(statement, ts.SyntaxKind.ExportKeyword)) continue; + if (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement)) continue; + if (hasModifier(statement, ts.SyntaxKind.DeclareKeyword)) return fail("Ambient runtime exports cannot be verified in an implementation file"); + const isDefault = hasModifier(statement, ts.SyntaxKind.DefaultKeyword); + if (ts.isFunctionDeclaration(statement)) { + if (!statement.name) { + exported.push({ name: "default", kind: "function" }); + continue; + } + if (exportedFunctions.has(statement.name.text)) continue; + exportedFunctions.add(statement.name.text); + const added = addLocal(statement.name.text, isDefault ? "default" : statement.name.text); + if (added.isErr()) return err(added.error); + } else if (ts.isVariableStatement(statement)) { + for (const declaration of statement.declarationList.declarations) { + for (const name of bindingNames(declaration.name)) { + const added = addLocal(name, name); + if (added.isErr()) return err(added.error); + } + } + } else if (ts.isClassDeclaration(statement) || ts.isEnumDeclaration(statement) || ts.isModuleDeclaration(statement)) { + exported.push({ name: isDefault ? "default" : statement.name?.text ?? "default", kind: "value" }); + } else return fail("Unsupported runtime export declaration"); + } + return ok(exported); +}; diff --git a/apps/anatomy-cli/src/cli.ts b/apps/anatomy-cli/src/cli.ts index d865efc..8439d45 100644 --- a/apps/anatomy-cli/src/cli.ts +++ b/apps/anatomy-cli/src/cli.ts @@ -1,5 +1,5 @@ import { err, ok, type Result } from "neverthrow"; -import { checkAnatomy, queryAnatomy, type AnatomyFileTreeEntry } from "@anatomy-cli/anatomy/core"; +import { checkAnatomy, planAnatomyCheck, queryAnatomy, type AnatomyFileTreeEntry } from "@anatomy-cli/anatomy/core"; import type { AnatomyDraftInput } from "@anatomy-cli/schemas"; import { AnatomyCliUsage, parseCliArguments, type AnatomyCliOptions } from "./cli-arguments"; import { @@ -11,6 +11,7 @@ import { } from "./filesystem"; import { formatHumanResult } from "./format-result"; import { formatAgentCheck, formatAgentQuery } from "./format-agent-result"; +import { collectSourceExports } from "./collect-source-exports"; export const AnatomyCliExitCode = { success: 0, @@ -30,6 +31,7 @@ export type AnatomyCliDependencies = { ignoredNames: string[], ) => Promise>; writeOutput: (value: string) => void; + collectExports?: typeof collectSourceExports; }; const defaultDependencies: AnatomyCliDependencies = { @@ -76,8 +78,14 @@ export const runAnatomyCli = async ( return ok(AnatomyCliExitCode.success); } - const checked = checkAnatomy(definition.value, tree.value); + const plan = planAnatomyCheck(definition.value, tree.value); + if (plan.isErr()) return err(new AnatomyDefinitionFileError( + plan.error.map((issue) => issue.message).join("; "), definitionPath.value)); + const sourceExports = await (dependencies.collectExports ?? collectSourceExports)(options.targetPath, plan.value.exportChecks); + if (sourceExports.isErr()) return err(sourceExports.error); + const checked = checkAnatomy(definition.value, tree.value, sourceExports.value); if (checked.isErr()) { + if (!Array.isArray(checked.error)) return err(checked.error); return err( new AnatomyDefinitionFileError( `Anatomy definition failed structural validation: ${checked.error.map((issue) => issue.message).join("; ")}`, diff --git a/apps/anatomy-cli/src/collect-source-exports.ts b/apps/anatomy-cli/src/collect-source-exports.ts new file mode 100644 index 0000000..5aadce1 --- /dev/null +++ b/apps/anatomy-cli/src/collect-source-exports.ts @@ -0,0 +1,24 @@ +import { readFile } from "node:fs/promises"; +import { resolve } from "node:path"; +import { err, ok, ResultAsync, type Result } from "neverthrow"; +import { AnatomySourceAnalysisError } from "@anatomy-cli/anatomy/core"; +import type { AnatomyFunctionExportCheck, AnatomySourceExports } from "@anatomy-cli/schemas"; +import { analyzeSourceExports } from "./analyze-source-exports"; + +export const collectSourceExports = async ( + targetPath: string, + checks: AnatomyFunctionExportCheck[], +): Promise, AnatomySourceAnalysisError>> => { + const inventory = new Map(); + for (const check of checks) { + if (inventory.has(check.path)) continue; + const path = resolve(targetPath, check.path); + const source = await ResultAsync.fromPromise(readFile(path, "utf8"), + () => new AnatomySourceAnalysisError(path, `Unable to read source file ${path}`)); + if (source.isErr()) return err(source.error); + const analyzed = analyzeSourceExports(path, source.value); + if (analyzed.isErr()) return err(analyzed.error); + inventory.set(check.path, analyzed.value); + } + return ok(inventory); +}; diff --git a/apps/anatomy-cli/src/format-agent-result.spec.ts b/apps/anatomy-cli/src/format-agent-result.spec.ts index c80d69d..3752bfc 100644 --- a/apps/anatomy-cli/src/format-agent-result.spec.ts +++ b/apps/anatomy-cli/src/format-agent-result.spec.ts @@ -23,6 +23,17 @@ const definition = AnatomyDraftInputSchema.parse({ }); describe("human query output", () => { + it("explains a file's export requirement with the resolved name", () => { + const input = AnatomyDraftInputSchema.parse({ + ...definition, structure: { ...definition.structure, root: { children: [{ + kind: "file", name: { type: "placeholder", value: ".ts" }, quantity: "one_or_more", exports: { name: "file_stem" }, + }] } }, + }); + const query = queryAnatomy(input, "getUser.ts")._unsafeUnwrap(); + const text = formatAgentQuery(query, input, "anatomy.json", ".", "human"); + expect(text).toContain('Export: exactly one named function "getUser" (BLOCK)'); + expect(text).toContain("type exports do not count; default exports are not allowed"); + }); it("explains inherited names, optional alternatives and policy overrides without a JSON dump", () => { const query = queryAnatomy(definition, "UserService")._unsafeUnwrap(); const text = formatAgentQuery(query, definition, "anatomy.json", ".", "human"); diff --git a/apps/anatomy-cli/src/format-agent-result.ts b/apps/anatomy-cli/src/format-agent-result.ts index 243ab42..1326e76 100644 --- a/apps/anatomy-cli/src/format-agent-result.ts +++ b/apps/anatomy-cli/src/format-agent-result.ts @@ -1,5 +1,5 @@ import { resolve } from "node:path"; -import { AnatomyCheckCode, anatomyRulePaths, type AnatomyCheckResult, type AnatomyFileTreeEntry } from "@anatomy-cli/anatomy/core"; +import { AnatomyCheckCode, anatomyRulePaths, resolveAnatomyExportName, type AnatomyCheckResult, type AnatomyFileTreeEntry } from "@anatomy-cli/anatomy/core"; import type { AnatomyCheckWithDiagnostics, AnatomyDraftInput, AnatomyNode, AnatomyPolicies, AnatomyQueryWithConstraints, AnatomyQuantity } from "@anatomy-cli/schemas"; import { DefaultIgnoredNames } from "./filesystem"; @@ -86,6 +86,9 @@ export const formatAgentQuery = ( ); return [ `${indent}${node.kind} ${name} — ${quantities[node.quantity]}`, + ...(node.kind === "file" && node.exports ? [ + `${indent} Export: exactly one named function "${resolveAnatomyExportName(node.exports, name, result.captures)}" (${node.exports.policy.toUpperCase()}); type exports do not count; default exports are not allowed`, + ] : []), ...(overrides.length ? [`${indent} Policies: ${policies(effective)}`] : []), ...(node.kind === "directory" ? node.children.flatMap((child) => ruleLines(child, effective, depth + 1)) : []), ]; diff --git a/apps/anatomy-cli/src/function-export-workflow.spec.ts b/apps/anatomy-cli/src/function-export-workflow.spec.ts new file mode 100644 index 0000000..c3a5a1f --- /dev/null +++ b/apps/anatomy-cli/src/function-export-workflow.spec.ts @@ -0,0 +1,98 @@ +import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; +import { join, resolve } from "node:path"; +import { afterEach, beforeEach, describe, expect, it } from "vitest"; +import { AnatomyCheckWithDiagnosticsSchema } from "@anatomy-cli/schemas"; +import { runAnatomyCli } from "./cli"; +import { collectFileTree, findAnatomyDefinition, readAnatomyDefinition } from "./filesystem"; +import { collectSourceExports } from "./collect-source-exports"; + +const verificationRoot = resolve(import.meta.dirname, "../../../docs/verification/function-export-tests"); +let directory: string; +const contract = () => ({ + name: "Function modules", purpose: "One function per file", + structure: { + schemaVersion: 1, + defaultPolicies: { missingRequired: "block", unexpectedEntry: "block", nameMismatch: "block", nestingMismatch: "block" }, + root: { children: [{ + kind: "file", name: { type: "placeholder", value: ".ts" }, quantity: "one_or_more", exports: { name: "file_stem" }, + }] }, + }, +}); +beforeEach(async () => { + await mkdir(verificationRoot, { recursive: true }); + directory = await mkdtemp(join(verificationRoot, "case-")); + await writeFile(join(directory, "anatomy.json"), JSON.stringify(contract())); +}); +afterEach(async () => { await rm(directory, { recursive: true, force: true }); }); + +const invoke = async (args: string[] = []) => { + const output: string[] = []; + const result = await runAnatomyCli([directory, "--format", "json", ...args], { + findDefinition: findAnatomyDefinition, + readDefinition: async (path) => readAnatomyDefinition(path), + collectTree: collectFileTree, + writeOutput: (value) => output.push(value), + }); + return { result, output: output.join("\n") }; +}; + +describe("function export CLI workflow", () => { + it("queries, catches a wrong export, then passes after correcting source in place", async () => { + const queried = await invoke(["--query", "getUser.ts"]); + const query = JSON.parse(queried.output); + expect(query.rules[0].expectedExport).toBe("getUser"); + await writeFile(join(directory, "getUser.ts"), "export function getOrder() {}\n"); + const blocked = await invoke(); + expect(blocked.result._unsafeUnwrap()).toBe(1); + const report = AnatomyCheckWithDiagnosticsSchema.parse(JSON.parse(blocked.output)); + expect(report.issues[0]).toMatchObject({ + code: "export_name_mismatch", expectedExport: "getUser", rulePath: query.rules[0].rulePath, + actualExports: [{ name: "getOrder", kind: "function" }], + }); + await writeFile(join(directory, "getUser.ts"), "export type User = {}; export const getUser = () => ({});\n"); + const passed = await invoke(); + expect(passed.result._unsafeUnwrap()).toBe(0); + expect(JSON.parse(passed.output)).toMatchObject({ conforms: true, issues: [] }); + }); + + it.each([ + { source: "const getUser = () => {};", code: "export_count_mismatch" }, + { source: "export default function getUser() {}", code: "export_name_mismatch" }, + { source: "export const getUser = 1;", code: "export_kind_mismatch" }, + { source: "export function getUser() {} export const version = 1;", code: "export_count_mismatch" }, + { source: "export type getUser = {};", code: "export_count_mismatch" }, + ])("blocks $code from real source", async ({ source, code }) => { + await writeFile(join(directory, "getUser.ts"), source); + const run = await invoke(); + expect(run.result._unsafeUnwrap()).toBe(1); + expect(JSON.parse(run.output).issues[0].code).toBe(code); + }); + + it.each(["export function ( {", "export * from './other';"])("reports unsupported analysis as an operational error: %s", async (source) => { + await writeFile(join(directory, "getUser.ts"), source); + const run = await invoke(); + expect(run.result._unsafeUnwrapErr()).toMatchObject({ name: "AnatomySourceAnalysisError" }); + expect(run.output).toBe(""); + }); + + it("does not parse source in query mode", async () => { + await writeFile(join(directory, "getUser.ts"), "export function ( {"); + const run = await invoke(["--query", "getUser.ts"]); + expect(run.result._unsafeUnwrap()).toBe(0); + expect(JSON.parse(run.output).status).toBe("resolved"); + }); + + it("fails explicitly when a selected source file cannot be read", async () => { + const result = await collectSourceExports(directory, [{ path: "missing.ts", expectedName: "missing", policy: "block", constraintId: "missing" }]); + expect(result.isErr()).toBe(true); + }); + + it("leaves source analysis opt-in for existing definitions", async () => { + const document = contract(); + Reflect.deleteProperty(document.structure.root.children[0]!, "exports"); + await writeFile(join(directory, "anatomy.json"), JSON.stringify(document)); + await writeFile(join(directory, "getUser.ts"), "not valid JavaScript: {{{"); + const run = await invoke(); + expect(run.result._unsafeUnwrap()).toBe(0); + }); +}); diff --git a/apps/anatomy-cli/src/index.ts b/apps/anatomy-cli/src/index.ts index 649cc88..2189b27 100644 --- a/apps/anatomy-cli/src/index.ts +++ b/apps/anatomy-cli/src/index.ts @@ -3,3 +3,5 @@ export * from "./cli-arguments"; export * from "./filesystem"; export * from "./format-result"; export * from "./format-agent-result"; +export * from "./analyze-source-exports"; +export * from "./collect-source-exports"; diff --git a/apps/anatomy-cli/src/source-contract.spec.ts b/apps/anatomy-cli/src/source-contract.spec.ts index 2ecc927..a9a1eef 100644 --- a/apps/anatomy-cli/src/source-contract.spec.ts +++ b/apps/anatomy-cli/src/source-contract.spec.ts @@ -1,7 +1,8 @@ import { resolve } from "node:path"; import { describe, expect, it } from "vitest"; -import { checkAnatomy } from "@anatomy-cli/anatomy/core"; +import { checkAnatomy, planAnatomyCheck } from "@anatomy-cli/anatomy/core"; import { collectFileTree, readAnatomyDefinition } from "./filesystem"; +import { collectSourceExports } from "./collect-source-exports"; describe("CLI source contract", () => { it("checks the real source directory against the shipped example definition", async () => { @@ -9,13 +10,16 @@ describe("CLI source contract", () => { resolve(import.meta.dirname, "../anatomies/cli-source.anatomy.json"), ))._unsafeUnwrap(); const entries = (await collectFileTree(import.meta.dirname))._unsafeUnwrap(); - const result = checkAnatomy(definition, entries)._unsafeUnwrap(); + const plan = planAnatomyCheck(definition, entries)._unsafeUnwrap(); + const exports = (await collectSourceExports(import.meta.dirname, plan.exportChecks))._unsafeUnwrap(); + expect(exports.size).toBeGreaterThan(0); + const result = checkAnatomy(definition, entries, exports)._unsafeUnwrap(); expect(result.issues).toEqual([]); expect(result.conforms).toBe(true); - expect(checkAnatomy(definition, entries.filter((entry) => entry.name !== "cli.ts")) + expect(checkAnatomy(definition, entries.filter((entry) => entry.name !== "cli.ts"), exports) ._unsafeUnwrap().conforms).toBe(false); - expect(checkAnatomy(definition, [...entries, { kind: "file", name: "undeclared.ts" }]) + expect(checkAnatomy(definition, [...entries, { kind: "file", name: "undeclared.ts" }], exports) ._unsafeUnwrap().conforms).toBe(false); }); }); diff --git a/packages/anatomy/src/core/anatomy-export-name.ts b/packages/anatomy/src/core/anatomy-export-name.ts new file mode 100644 index 0000000..76554e9 --- /dev/null +++ b/packages/anatomy/src/core/anatomy-export-name.ts @@ -0,0 +1,11 @@ +import type { AnatomyFunctionExportRule } from "@anatomy-cli/schemas"; + +export const resolveAnatomyExportName = ( + rule: AnatomyFunctionExportRule, + filename: string, + captures: Readonly>, +): string => { + if (rule.name === "file_stem") return filename.replace(/\.[^.]+$/, ""); + if (rule.name.type === "literal") return rule.name.value; + return rule.name.value.replace(/<([^<>]+)>/, (placeholder, name: string) => captures[name] ?? placeholder); +}; diff --git a/packages/anatomy/src/core/check-anatomy.ts b/packages/anatomy/src/core/check-anatomy.ts index 8693766..9f0670c 100644 --- a/packages/anatomy/src/core/check-anatomy.ts +++ b/packages/anatomy/src/core/check-anatomy.ts @@ -6,7 +6,10 @@ import { type AnatomyNode, type AnatomyPolicies, type AnatomyPolicyOverrides, + type AnatomyFunctionExportCheck, + type AnatomySourceExports, } from "@anatomy-cli/schemas"; +import { resolveAnatomyExportName } from "./anatomy-export-name"; import { resolveAnatomyPolicies } from "./resolveAnatomyPolicies"; import { validateAnatomyForPublish, @@ -27,6 +30,9 @@ export const AnatomyCheckCode = { nestingMismatch: "nesting_mismatch", quantityExceeded: "quantity_exceeded", oneOfMismatch: "one_of_mismatch", + exportCountMismatch: "export_count_mismatch", + exportNameMismatch: "export_name_mismatch", + exportKindMismatch: "export_kind_mismatch", } as const; export type AnatomyCheckIssue = { @@ -35,6 +41,8 @@ export type AnatomyCheckIssue = { path: string; constraintId: string | null; message: string; + expectedExport?: string; + actualExports?: AnatomySourceExports; }; export type AnatomyCheckResult = { @@ -103,14 +111,15 @@ const getEntryLabel = (entry: AnatomyEntry): string => { return entry.name.value; }; -export const checkAnatomy = ( +export const planAnatomyCheck = ( definition: AnatomyDraftInput, entries: AnatomyFileTreeEntry[], -): ResultType => { +): ResultType<{ structuralResult: AnatomyCheckResult; exportChecks: AnatomyFunctionExportCheck[] }, AnatomyValidationIssue[]> => { const validated = validateAnatomyForPublish(definition); if (validated.isErr()) return err(validated.error); const issues: AnatomyCheckIssue[] = []; + const exportChecks: AnatomyFunctionExportCheck[] = []; const defaults = definition.structure.defaultPolicies; const bindings = definition.structure.bindings ?? {}; @@ -262,6 +271,14 @@ export const checkAnatomy = ( }); } + if (entry.kind === "file" && actual.kind === "file" && entry.exports) { + exportChecks.push({ + path: joinPath(parentPath, actual.name), constraintId: entry.id, + expectedName: resolveAnatomyExportName(entry.exports, actual.name, { ...scope, ...candidate.match.captures }), + policy: entry.exports.policy, + }); + } + if (entry.kind === "directory" && actual.kind === "directory") { checkNodes(entry.children, actual.children, joinPath(parentPath, actual.name), [ ...ancestors, @@ -328,5 +345,47 @@ export const checkAnatomy = ( { block: 0, warn: 0, allow: 0 }, ); - return ok({ issues, summary, conforms: summary.block === 0 }); + return ok({ structuralResult: { issues, summary, conforms: summary.block === 0 }, exportChecks }); +}; + +export class AnatomySourceAnalysisError extends Error { + constructor(public readonly path: string, message: string) { + super(message); + this.name = "AnatomySourceAnalysisError"; + } +} + +export const checkAnatomy = ( + definition: AnatomyDraftInput, + entries: AnatomyFileTreeEntry[], + sourceExports: ReadonlyMap = new Map(), +): ResultType => { + const plan = planAnatomyCheck(definition, entries); + if (plan.isErr()) return err(plan.error); + const { structuralResult, exportChecks } = plan.value; + for (const check of exportChecks) { + const actual = sourceExports.get(check.path); + if (actual === undefined) return err(new AnatomySourceAnalysisError(check.path, `Exports were not analyzed for ${check.path}`)); + const addIssue = (code: AnatomyCheckIssue["code"], message: string) => { + structuralResult.issues.push({ + code, message, severity: check.policy, path: check.path, constraintId: check.constraintId, + expectedExport: check.expectedName, actualExports: actual, + }); + structuralResult.summary[check.policy] += 1; + }; + if (actual.length !== 1) { + addIssue(AnatomyCheckCode.exportCountMismatch, + `Expected exactly one named function export "${check.expectedName}" but found ${actual.length} runtime exports`); + continue; + } + const exported = actual[0]!; + if (exported.name === "default" || exported.name !== check.expectedName) { + addIssue(AnatomyCheckCode.exportNameMismatch, `Expected named export "${check.expectedName}" but found "${exported.name}"`); + } + if (exported.kind !== "function") { + addIssue(AnatomyCheckCode.exportKindMismatch, `Expected function export "${check.expectedName}" but found a non-function value`); + } + } + structuralResult.conforms = structuralResult.summary.block === 0; + return ok(structuralResult); }; diff --git a/packages/anatomy/src/core/function-export.spec.ts b/packages/anatomy/src/core/function-export.spec.ts new file mode 100644 index 0000000..c7c1bec --- /dev/null +++ b/packages/anatomy/src/core/function-export.spec.ts @@ -0,0 +1,100 @@ +import { describe, expect, it } from "vitest"; +import { AnatomyDraftInputSchema, type AnatomySourceExports } from "@anatomy-cli/schemas"; +import { checkAnatomy, planAnatomyCheck } from "./check-anatomy"; +import { queryAnatomy } from "./query-anatomy"; + +const definition = () => AnatomyDraftInputSchema.parse({ + name: "Function files", purpose: "One named function per file", + structure: { + schemaVersion: 1, + defaultPolicies: { missingRequired: "block", unexpectedEntry: "block", nameMismatch: "block", nestingMismatch: "block" }, + root: { children: [{ + kind: "file", name: { type: "placeholder", value: ".ts" }, quantity: "one_or_more", + exports: { name: "file_stem" }, + }] }, + }, +}); +const entries = [{ kind: "file" as const, name: "getUser.ts" }]; +const inspect = (exports: AnatomySourceExports) => checkAnatomy(definition(), entries, new Map([["getUser.ts", exports]]))._unsafeUnwrap(); + +describe("function export contracts", () => { + it("accepts exactly one correctly named function", () => { + expect(inspect([{ name: "getUser", kind: "function" }])).toMatchObject({ conforms: true, issues: [] }); + }); + it.each([ + { exports: [], code: "export_count_mismatch" }, + { exports: [{ name: "getOrder", kind: "function" }], code: "export_name_mismatch" }, + { exports: [{ name: "default", kind: "function" }], code: "export_name_mismatch" }, + { exports: [{ name: "getUser", kind: "value" }], code: "export_kind_mismatch" }, + { exports: [{ name: "getUser", kind: "function" }, { name: "other", kind: "function" }], code: "export_count_mismatch" }, + ] satisfies { exports: AnatomySourceExports; code: string }[])("blocks $code", ({ exports, code }) => { + const result = inspect(exports); + expect(result.conforms).toBe(false); + expect(result.issues).toEqual([expect.objectContaining({ code, path: "getUser.ts", expectedExport: "getUser", actualExports: exports })]); + }); + it("fails closed when a caller skips source analysis", () => { + expect(checkAnatomy(definition(), entries)._unsafeUnwrapErr()).toMatchObject({ name: "AnatomySourceAnalysisError", path: "getUser.ts" }); + }); + it("does not read source for unmatched files or absent optional entries", () => { + const input = definition(); + expect(planAnatomyCheck(input, [{ kind: "file", name: "readme.md" }])._unsafeUnwrap().exportChecks).toEqual([]); + expect(checkAnatomy(input, [])._unsafeUnwrap().issues[0]?.code).toBe("missing_required"); + }); + it("resolves a captured method name without including the suffix", () => { + const input = definition(); + const file = input.structure.root.children[0]!; + if (file.kind !== "file") throw new Error("Expected file fixture"); + file.name.value = ".method.ts"; + file.exports = { name: { type: "placeholder", value: "" }, policy: "block" }; + const plan = planAnatomyCheck(input, [{ kind: "file", name: "getUser.method.ts" }])._unsafeUnwrap(); + expect(plan.exportChecks[0]?.expectedName).toBe("getUser"); + expect(queryAnatomy(input, "getUser.method.ts")._unsafeUnwrap().rules[0]?.node).toMatchObject({ exports: file.exports }); + }); + it("rejects export placeholders that are not bound by the file path", () => { + const input = definition(); + const file = input.structure.root.children[0]!; + if (file.kind !== "file") throw new Error("Expected file fixture"); + file.exports = { name: { type: "placeholder", value: "" }, policy: "block" }; + expect(queryAnatomy(input, "getUser.ts").isErr()).toBe(true); + expect(planAnatomyCheck(input, entries).isErr()).toBe(true); + }); + it("inherits export names from directories and keeps repeated scopes independent", () => { + const input = definition(); + const original = input.structure.root.children[0]!; + input.structure.root.children = [{ + id: crypto.randomUUID(), kind: "directory", name: { type: "placeholder", value: "" }, + quantity: "one_or_more", policyOverrides: {}, children: [{ + ...original, kind: "file", name: { type: "literal", value: "index.ts" }, + quantity: "exactly_one", policyOverrides: {}, + exports: { name: { type: "placeholder", value: "" }, policy: "block" }, + }], + }]; + const tree = ["getUser", "getOrder"].map((name) => ({ + kind: "directory" as const, name, children: [{ kind: "file" as const, name: "index.ts" }], + })); + const plan = planAnatomyCheck(input, tree)._unsafeUnwrap(); + expect(plan.exportChecks.map((check) => check.expectedName)).toEqual(["getUser", "getOrder"]); + expect(queryAnatomy(input, "getUser/index.ts")._unsafeUnwrap().rules[0]?.expectedExport).toBe("getUser"); + }); + it("plans only consumed alternatives when file patterns overlap", () => { + const input = definition(); + const original = input.structure.root.children[0]!; + input.structure.root.children = [{ + id: crypto.randomUUID(), kind: "one_of", minimumMatches: 1, maximumMatches: 1, + alternatives: [{ + ...original, kind: "file", name: { type: "literal", value: "getUser.ts" }, + quantity: "exactly_one", policyOverrides: {}, exports: { name: "file_stem", policy: "block" }, + }, { + ...original, id: crypto.randomUUID(), kind: "file", name: { type: "literal", value: "getOrder.ts" }, + quantity: "exactly_one", policyOverrides: {}, exports: { name: "file_stem", policy: "block" }, + }], + }, { ...original, id: crypto.randomUUID() }]; + expect(planAnatomyCheck(input, entries)._unsafeUnwrap().exportChecks).toHaveLength(1); + }); + it("keeps existing structural-only definitions working without source analysis", () => { + const input = definition(); + const file = input.structure.root.children[0]!; + if (file.kind === "file") delete file.exports; + expect(checkAnatomy(input, entries)._unsafeUnwrap().conforms).toBe(true); + }); +}); diff --git a/packages/anatomy/src/core/index.ts b/packages/anatomy/src/core/index.ts index e79d6a4..6434ed6 100644 --- a/packages/anatomy/src/core/index.ts +++ b/packages/anatomy/src/core/index.ts @@ -7,3 +7,4 @@ export * from "./validate-anatomy-for-publish"; export * from "./anatomy-rule-paths"; export * from "./query-anatomy"; export * from "./match-anatomy-name"; +export * from "./anatomy-export-name"; diff --git a/packages/anatomy/src/core/query-anatomy.ts b/packages/anatomy/src/core/query-anatomy.ts index d3d0d67..dba09dc 100644 --- a/packages/anatomy/src/core/query-anatomy.ts +++ b/packages/anatomy/src/core/query-anatomy.ts @@ -3,6 +3,7 @@ import { AnatomyQueryWithConstraintsSchema, type AnatomyDraftInput, type Anatomy import { evaluateName } from "./match-anatomy-name"; import { resolveAnatomyPolicies } from "./resolveAnatomyPolicies"; import { anatomyRulePaths } from "./anatomy-rule-paths"; +import { resolveAnatomyExportName } from "./anatomy-export-name"; import { validateAnatomyForPublish, type AnatomyValidationIssue } from "./validate-anatomy-for-publish"; const QueryStatus = AnatomyQueryWithConstraintsSchema.shape.status.enum; @@ -45,12 +46,17 @@ export const queryAnatomy = ( nestingMismatch: resolved.nestingMismatch.value, }; }; - const describe = (nodes: AnatomyNode[]) => nodes.map((node) => ({ - rulePath: registry.get(node.id)!.rulePath, node, policies: policiesFor(node), - expectedName: node.kind === "one_of" ? null : node.name.type === "literal" ? node.name.value : node.name.value.replace( + const describe = (nodes: AnatomyNode[]) => nodes.map((node) => { + const expectedName = node.kind === "one_of" ? null : node.name.type === "literal" ? node.name.value : node.name.value.replace( /<([^<>]+)>/, (placeholder, name: string) => result.captures[name] ?? placeholder, - ), - })); + ); + return { + rulePath: registry.get(node.id)!.rulePath, node, policies: policiesFor(node), expectedName, + ...(node.kind === "file" && node.exports ? { + expectedExport: resolveAnatomyExportName(node.exports, expectedName!, result.captures), + } : {}), + }; + }); let nodes = definition.structure.root.children; result.rules = describe(nodes); diff --git a/packages/anatomy/src/core/validate-anatomy-for-publish.ts b/packages/anatomy/src/core/validate-anatomy-for-publish.ts index 1193eb2..fe86318 100644 --- a/packages/anatomy/src/core/validate-anatomy-for-publish.ts +++ b/packages/anatomy/src/core/validate-anatomy-for-publish.ts @@ -12,13 +12,14 @@ export const AnatomyValidationCode = { absolutePath: "absolute_path", invalidOneOfRange: "invalid_one_of_range", impossibleOneOf: "impossible_one_of", + invalidExportName: "invalid_export_name", } as const; export type AnatomyValidationIssue = { code: (typeof AnatomyValidationCode)[keyof typeof AnatomyValidationCode]; nodeId: string; parentId: string | null; - field: "id" | "name" | "binding" | "minimumMatches" | "maximumMatches"; + field: "id" | "name" | "binding" | "minimumMatches" | "maximumMatches" | "exports"; message: string; }; @@ -160,7 +161,7 @@ export const validateAnatomyForPublish = ( } }; - const visitNodes = (nodes: AnatomyNode[], parentId: string | null) => { + const visitNodes = (nodes: AnatomyNode[], parentId: string | null, inheritedBindings: string[] = []) => { validateDuplicateLiteralNames(nodes, parentId); for (const node of nodes) { @@ -194,13 +195,26 @@ export const validateAnatomyForPublish = ( }); } - visitNodes(node.alternatives, node.id); + visitNodes(node.alternatives, node.id, inheritedBindings); continue; } validateName(node, parentId); + const captured = node.name.type === "placeholder" ? /<([^<>]+)>/.exec(node.name.value)?.[1] : undefined; + const availableBindings = captured ? [...inheritedBindings, captured] : inheritedBindings; + if (node.kind === "file" && node.exports && node.exports.name !== "file_stem") { + const name = node.exports.name; + const binding = /<([^<>]+)>/.exec(name.value)?.[1]; + if (isRealPathExpression(name.value) || + (name.type === "placeholder" && (!PlaceholderPattern.test(name.value) || !binding || !availableBindings.includes(binding)))) { + issues.push({ + code: AnatomyValidationCode.invalidExportName, nodeId: node.id, parentId, field: "exports", + message: `Export name "${name.value}" must be a name expression whose placeholder is captured by this file or an ancestor directory`, + }); + } + } if (node.kind === "directory") { - visitNodes(node.children, node.id); + visitNodes(node.children, node.id, availableBindings); } } }; diff --git a/packages/schemas/src/anatomy/AnatomyCheckWithDiagnosticsSchema.ts b/packages/schemas/src/anatomy/AnatomyCheckWithDiagnosticsSchema.ts index 6f4f062..412f719 100644 --- a/packages/schemas/src/anatomy/AnatomyCheckWithDiagnosticsSchema.ts +++ b/packages/schemas/src/anatomy/AnatomyCheckWithDiagnosticsSchema.ts @@ -1,6 +1,7 @@ import { z } from "zod/v4"; import { AnatomyNodeSchema } from "./AnatomyNode.schema"; import { AnatomyPolicyValueSchema } from "./AnatomyPolicyValue.schema"; +import { AnatomySourceExportsSchema } from "./AnatomySourceExportsSchema"; export const AnatomyCheckWithDiagnosticsSchema = z.object({ contractVersion: z.literal(1), @@ -13,6 +14,8 @@ export const AnatomyCheckWithDiagnosticsSchema = z.object({ path: z.string(), constraintId: z.string().nullable(), message: z.string(), + expectedExport: z.string().optional(), + actualExports: AnatomySourceExportsSchema.optional(), rulePath: z.string().nullable(), expected: AnatomyNodeSchema.nullable(), actual: z.array(z.object({ kind: z.enum(["file", "directory"]), name: z.string() })), diff --git a/packages/schemas/src/anatomy/AnatomyContract.spec.ts b/packages/schemas/src/anatomy/AnatomyContract.spec.ts index 39b9475..47f800a 100644 --- a/packages/schemas/src/anatomy/AnatomyContract.spec.ts +++ b/packages/schemas/src/anatomy/AnatomyContract.spec.ts @@ -11,6 +11,20 @@ const definition = () => ({ }); describe("Anatomy definition compatibility", () => { + it("allows an explicit function export rule only on files", () => { + const input = definition(); + Object.assign(input.structure.root.children[0]!, { exports: { name: "file_stem" } }); + const parsed = AnatomyDraftInputSchema.safeParse(input); + expect(parsed.success).toBe(true); + if (parsed.success) expect(parsed.data.structure.root.children[0]).toMatchObject({ exports: { policy: "block" } }); + Object.assign(input.structure.root.children[0]!, { kind: "directory", children: [] }); + expect(AnatomyDraftInputSchema.safeParse(input).success).toBe(false); + }); + it("rejects unsupported export options", () => { + const input = definition(); + Object.assign(input.structure.root.children[0]!, { exports: { name: "file_stem", allowDefault: true } }); + expect(AnatomyDraftInputSchema.safeParse(input).success).toBe(false); + }); it("accepts version one with omitted IDs and overrides", () => { expect(AnatomyDraftInputSchema.safeParse(definition()).success).toBe(true); }); diff --git a/packages/schemas/src/anatomy/AnatomyDirectoryEntry.schema.ts b/packages/schemas/src/anatomy/AnatomyDirectoryEntry.schema.ts index 5b0267b..febbc31 100644 --- a/packages/schemas/src/anatomy/AnatomyDirectoryEntry.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyDirectoryEntry.schema.ts @@ -5,12 +5,12 @@ import { AnatomyNodeSchema, type AnatomyNode } from "./AnatomyNode.schema"; /** Directory node and its recursive children in an Anatomy tree. */ export const AnatomyDirectoryEntrySchema: z.ZodType< - Omit & { + Omit & { kind: "directory"; children: AnatomyNode[]; } > = z.lazy(() => - AnatomyFileEntrySchema.omit({ kind: true }).extend({ + AnatomyFileEntrySchema.omit({ kind: true, exports: true }).extend({ /** Node discriminant, fixed to directory. */ kind: z.literal("directory"), /** Structure nodes directly contained by the directory. */ diff --git a/packages/schemas/src/anatomy/AnatomyFileEntry.schema.ts b/packages/schemas/src/anatomy/AnatomyFileEntry.schema.ts index ddb760f..a8b6735 100644 --- a/packages/schemas/src/anatomy/AnatomyFileEntry.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyFileEntry.schema.ts @@ -3,6 +3,7 @@ import { z } from "zod/v4"; import { AnatomyNameExpressionSchema } from "./AnatomyNameExpression.schema"; import { AnatomyPolicyOverridesSchema } from "./AnatomyPolicyOverrides.schema"; import { AnatomyQuantitySchema } from "./AnatomyQuantity.schema"; +import { AnatomyFunctionExportRuleSchema } from "./AnatomyFunctionExportRuleSchema"; /** File requirement with naming, quantity, and policy constraints. */ export const AnatomyFileEntrySchema = z.strictObject({ @@ -16,6 +17,7 @@ export const AnatomyFileEntrySchema = z.strictObject({ policyOverrides: AnatomyPolicyOverridesSchema.default({}), /** Node discriminant, fixed to file. */ kind: z.literal("file"), + exports: AnatomyFunctionExportRuleSchema.optional(), }); export type AnatomyFileEntry = z.infer; diff --git a/packages/schemas/src/anatomy/AnatomyFunctionExportCheckSchema.ts b/packages/schemas/src/anatomy/AnatomyFunctionExportCheckSchema.ts new file mode 100644 index 0000000..66f2dc9 --- /dev/null +++ b/packages/schemas/src/anatomy/AnatomyFunctionExportCheckSchema.ts @@ -0,0 +1,11 @@ +import { z } from "zod/v4"; +import { AnatomyPolicyValueSchema } from "./AnatomyPolicyValue.schema"; + +export const AnatomyFunctionExportCheckSchema = z.strictObject({ + path: z.string(), + constraintId: z.string(), + expectedName: z.string(), + policy: AnatomyPolicyValueSchema, +}); + +export type AnatomyFunctionExportCheck = z.infer; diff --git a/packages/schemas/src/anatomy/AnatomyFunctionExportRuleSchema.ts b/packages/schemas/src/anatomy/AnatomyFunctionExportRuleSchema.ts new file mode 100644 index 0000000..e0d18fe --- /dev/null +++ b/packages/schemas/src/anatomy/AnatomyFunctionExportRuleSchema.ts @@ -0,0 +1,10 @@ +import { z } from "zod/v4"; +import { AnatomyNameExpressionSchema } from "./AnatomyNameExpression.schema"; +import { AnatomyPolicyValueSchema } from "./AnatomyPolicyValue.schema"; + +export const AnatomyFunctionExportRuleSchema = z.strictObject({ + name: z.union([z.literal("file_stem"), AnatomyNameExpressionSchema]), + policy: AnatomyPolicyValueSchema.default("block"), +}); + +export type AnatomyFunctionExportRule = z.infer; diff --git a/packages/schemas/src/anatomy/AnatomyQueryWithConstraintsSchema.ts b/packages/schemas/src/anatomy/AnatomyQueryWithConstraintsSchema.ts index 7a5c5c7..b9bbee4 100644 --- a/packages/schemas/src/anatomy/AnatomyQueryWithConstraintsSchema.ts +++ b/packages/schemas/src/anatomy/AnatomyQueryWithConstraintsSchema.ts @@ -24,6 +24,7 @@ export const AnatomyQueryWithConstraintsSchema = z.object({ rulePath: z.string(), node: AnatomyNodeSchema, expectedName: z.string().nullable(), + expectedExport: z.string().optional(), policies: AnatomyPoliciesSchema, })), matches: z.array(z.string()), diff --git a/packages/schemas/src/anatomy/AnatomySourceExportsSchema.ts b/packages/schemas/src/anatomy/AnatomySourceExportsSchema.ts new file mode 100644 index 0000000..ca49b38 --- /dev/null +++ b/packages/schemas/src/anatomy/AnatomySourceExportsSchema.ts @@ -0,0 +1,8 @@ +import { z } from "zod/v4"; + +export const AnatomySourceExportsSchema = z.array(z.strictObject({ + name: z.string(), + kind: z.enum(["function", "value"]), +})); + +export type AnatomySourceExports = z.infer; diff --git a/packages/schemas/src/anatomy/index.ts b/packages/schemas/src/anatomy/index.ts index 77897e1..8549862 100644 --- a/packages/schemas/src/anatomy/index.ts +++ b/packages/schemas/src/anatomy/index.ts @@ -23,3 +23,6 @@ export * from "./AnatomySummary.schema"; export * from "./AnatomyVersion.schema"; export * from "./AnatomyQueryWithConstraintsSchema"; export * from "./AnatomyCheckWithDiagnosticsSchema"; +export * from "./AnatomyFunctionExportRuleSchema"; +export * from "./AnatomySourceExportsSchema"; +export * from "./AnatomyFunctionExportCheckSchema"; From a9424315884ffe5e2adce03a8e12dbf6c5bbf05e Mon Sep 17 00:00:00 2001 From: Zander Zhang <276678881@qq.com> Date: Tue, 8 Sep 2026 01:02:03 +0800 Subject: [PATCH 3/8] feat: enforce repository-wide Anatomy self contracts --- .gitignore | 3 +- CONTRIBUTING.md | 38 + README.md | 26 +- README.zh-CN.md | 9 +- anatomy.coverage.json | 811 +++++++ anatomy.json | 1998 +++++++++++++++++ .../anatomies/cli-source.anatomy.json | 211 +- apps/anatomy-cli/bin/anatomy-cli.js | 2 +- apps/anatomy-cli/bin/anatomy.js | 2 +- .../bin/{run.js => runEntrypoint.js} | 0 apps/anatomy-cli/package.json | 6 +- .../src/AnatomyCliArgumentError.ts | 6 + apps/anatomy-cli/src/AnatomyCliExitCode.ts | 5 + .../anatomy-cli/src/AnatomyCliFormatValues.ts | 1 + apps/anatomy-cli/src/AnatomyCliUsage.ts | 15 + .../src/AnatomyDefinitionFileError.ts | 9 + apps/anatomy-cli/src/AnatomyFileTreeError.ts | 9 + apps/anatomy-cli/src/AnatomyInstallError.ts | 6 + .../src/DefaultAnatomyDefinitionFileName.ts | 1 + apps/anatomy-cli/src/DefaultIgnoredNames.ts | 13 + apps/anatomy-cli/src/agent-workflow.spec.ts | 12 +- .../src/analyze-source-exports.spec.ts | 2 +- ...rce-exports.ts => analyzeSourceExports.ts} | 0 apps/anatomy-cli/src/cli-arguments.spec.ts | 3 +- apps/anatomy-cli/src/cli.spec.ts | 8 +- apps/anatomy-cli/src/collectFileTree.ts | 53 + apps/anatomy-cli/src/collectGitFileTree.ts | 44 + ...rce-exports.ts => collectSourceExports.ts} | 2 +- .../src/{install-path.ts => configurePath.ts} | 36 +- apps/anatomy-cli/src/filesystem.spec.ts | 10 +- apps/anatomy-cli/src/filesystem.ts | 148 -- apps/anatomy-cli/src/findAnatomyDefinition.ts | 32 + .../src/format-agent-result.spec.ts | 6 +- apps/anatomy-cli/src/formatAgentCheck.ts | 44 + apps/anatomy-cli/src/formatAgentError.ts | 4 + ...at-agent-result.ts => formatAgentQuery.ts} | 47 +- ...{format-result.ts => formatHumanResult.ts} | 4 - apps/anatomy-cli/src/formatJsonResult.ts | 5 + .../src/function-export-workflow.spec.ts | 10 +- apps/anatomy-cli/src/getPathPlan.ts | 19 + apps/anatomy-cli/src/git-files.spec.ts | 84 + apps/anatomy-cli/src/index.ts | 28 +- apps/anatomy-cli/src/install-main.ts | 9 +- apps/anatomy-cli/src/install.spec.ts | 9 +- apps/anatomy-cli/src/installUsage.ts | 19 + apps/anatomy-cli/src/main.ts | 7 +- ...{cli-arguments.ts => parseCliArguments.ts} | 36 +- ...tall-options.ts => parseInstallOptions.ts} | 30 +- apps/anatomy-cli/src/posixLauncher.ts | 1 + apps/anatomy-cli/src/quoteShell.ts | 1 + apps/anatomy-cli/src/readAnatomyDefinition.ts | 40 + .../src/repository-contract.spec.ts | 156 ++ .../src/{cli.ts => runAnatomyCli.ts} | 39 +- .../src/{install.ts => runInstallation.ts} | 16 +- apps/anatomy-cli/src/source-contract.spec.ts | 9 +- apps/anatomy-cli/src/windowsLauncher.ts | 1 + apps/anatomy-cli/src/windowsPathScript.ts | 7 + apps/docs/package.json | 1 + apps/docs/scripts/check-cloudflare-build.ts | 2 +- .../AppBootScreen.lifecycle.test.tsx | 5 +- .../AppBootScreen/AppBootScreen.test.tsx | 9 +- .../AppBootScreen/AppBootScreen.tsx | 12 +- .../components/AppBootScreen/BOOT_MOTION.ts | 8 + .../src/components/AppBootScreen/OVERSCAN.ts | 1 + .../AppBootScreen/TRIANGLE_INRADIUS.ts | 3 + .../AppBootScreen/TRIANGLE_RADIUS.ts | 1 + .../AppBootScreen/TRIANGLE_VERTICES.ts | 12 + ...boot-geometry.ts => createBootGeometry.ts} | 19 +- .../{boot-motion.ts => createBootMotion.ts} | 35 +- .../AppBootScreen/getOpeningScale.ts | 5 + .../AppBootScreen/getTurnSettleMs.ts | 8 + .../src/components/AppBootScreen/index.ts | 12 + .../components/AppBootScreen/polygonPoints.ts | 3 + .../components/AppBootScreen/waitForBoot.ts | 13 + .../LanguageSwitcher/LanguageSwitcher.tsx | 2 +- .../MonoBlockCanvas/MonoBlockCanvas.tsx | 2 +- .../StartupHome/KiteDartPattern.tsx | 39 +- .../components/StartupHome/RhombusPattern.tsx | 3 +- .../StartupHome/StartupGridBackground.tsx | 24 +- .../components/StartupHome/StartupHeader.tsx | 10 +- .../components/StartupHome/StartupHero.tsx | 11 +- .../StartupHome/StartupScanSection.tsx | 5 +- .../StartupHome/StartupTerminalCase.test.tsx | 10 +- .../StartupHome/StartupTerminalCase.tsx | 8 +- .../StartupHome/StructureScanPreview.tsx | 29 +- .../StartupHome/StructureTreeRow.tsx | 2 +- .../StartupHome/TERMINAL_COMMAND.ts | 1 + .../StartupHome/TERMINAL_DEMO_TIMING.ts | 10 + apps/docs/src/components/StartupHome/add.ts | 3 + .../{rhombus.ts => createPenroseTiling.ts} | 44 +- .../StartupHome/createRhombusTiling.ts | 30 + ...erminalDemo.ts => getTerminalDemoFrame.ts} | 14 +- apps/docs/src/components/StartupHome/index.ts | 11 +- .../src/components/StartupHome/pointsToSvg.ts | 6 + .../src/components/StartupHome/scanRows.tsx | 19 + .../StartupHome/updateGridPatternHover.tsx | 17 + .../StartupHome/updateKiteDartHover.tsx | 29 + .../components/StartupHome/useTerminalDemo.ts | 3 +- .../src/components/icons/CODE_PATH_LABELS.ts | 7 + .../src/components/icons/CODE_PATH_MAP.ts | 7 + .../src/components/icons/CODE_PATH_ROUTE.ts | 3 + .../src/components/icons/CodePathMapIcon.tsx | 6 +- apps/docs/src/components/icons/codePathMap.ts | 49 - .../components/icons/createCodePathDots.ts | 24 + .../src/components/icons/getCodePathPoint.ts | 10 + apps/docs/src/components/icons/index.ts | 6 +- apps/docs/src/components/ui/Badge/Badge.tsx | 2 +- apps/docs/src/components/ui/Button/Button.tsx | 29 +- .../components/ui/Button/buttonVariants.tsx | 25 + apps/docs/src/components/ui/Button/index.ts | 1 + apps/docs/src/components/ui/Card/Card.tsx | 13 +- .../src/components/ui/Card/CardContent.tsx | 9 + .../src/components/ui/Card/CardHeader.tsx | 9 + apps/docs/src/components/ui/Card/index.ts | 2 + .../ui/DropdownMenu/DropdownMenu.tsx | 50 - .../ui/DropdownMenu/DropdownMenuContent.tsx | 29 + .../ui/DropdownMenu/DropdownMenuItem.tsx | 15 + .../ui/DropdownMenu/DropdownMenuSeparator.tsx | 9 + .../ui/DropdownMenu/DropdownMenuTrigger.tsx | 3 + .../src/components/ui/DropdownMenu/index.ts | 4 + apps/docs/src/{content.ts => docsEntries.ts} | 2 - apps/docs/src/getDocsEntry.ts | 3 + .../src/lib/PERSISTENT_DETECTION_OPTIONS.ts | 7 + apps/docs/src/lib/THEME_PREPAINT_SCRIPT.ts | 3 + apps/docs/src/lib/THEME_STORAGE_KEY.ts | 1 + apps/docs/src/lib/applySavedLanguage.ts | 14 + apps/docs/src/lib/applyTheme.ts | 5 + apps/docs/src/lib/{utils.ts => cn.ts} | 0 apps/docs/src/lib/getSavedLanguage.ts | 14 + apps/docs/src/lib/getSavedTheme.ts | 12 + .../{i18n-server.ts => getServerLanguage.ts} | 2 +- apps/docs/src/lib/i18n.ts | 55 +- apps/docs/src/lib/index.ts | 12 + apps/docs/src/lib/languageDetector.ts | 3 + apps/docs/src/lib/normalizeLanguage.ts | 7 + apps/docs/src/lib/saveTheme.ts | 10 + apps/docs/src/lib/theme.ts | 29 - .../src/pages/{docs-page.tsx => DocsPage.tsx} | 11 +- .../docs/src/pages/{home.tsx => HomePage.tsx} | 0 apps/docs/src/pages/index.ts | 2 + apps/docs/src/routes/$.tsx | 2 +- apps/docs/src/routes/-RootDocument.tsx | 6 +- apps/docs/src/routes/docs.$slug.tsx | 2 +- apps/docs/src/routes/index.tsx | 2 +- apps/docs/vite.config.ts | 6 +- bun.lock | 1 + package.json | 3 +- packages/anatomy/src/core/AnatomyCheckCode.ts | 14 + .../anatomy/src/core/AnatomyQueryPathError.ts | 6 + .../src/core/AnatomySourceAnalysisError.ts | 6 + .../anatomy/src/core/AnatomyValidationCode.ts | 13 + .../anatomy/src/core/anatomy-tree.spec.ts | 20 +- packages/anatomy/src/core/anatomy-tree.ts | 295 --- ...tomy-rule-paths.ts => anatomyRulePaths.ts} | 0 .../anatomy/src/core/check-anatomy.spec.ts | 12 +- packages/anatomy/src/core/checkAnatomy.ts | 44 + packages/anatomy/src/core/cloneEntry.ts | 5 + .../anatomy/src/core/createDirectoryEntry.ts | 17 + .../anatomy/src/core/createEmptyStructure.ts | 15 + packages/anatomy/src/core/createFileEntry.ts | 15 + ...{match-anatomy-name.ts => evaluateName.ts} | 0 packages/anatomy/src/core/findNodeInTree.ts | 20 + .../anatomy/src/core/function-export.spec.ts | 7 +- .../anatomy/src/core/groupSiblingEntries.ts | 58 + packages/anatomy/src/core/index.ts | 27 +- .../anatomy/src/core/insertAnatomyNode.ts | 28 + packages/anatomy/src/core/locateNodeInTree.ts | 42 + .../{check-anatomy.ts => planAnatomyCheck.ts} | 84 +- .../anatomy/src/core/query-anatomy.spec.ts | 6 +- .../{query-anatomy.ts => queryAnatomy.ts} | 18 +- .../anatomy/src/core/removeAnatomyNode.ts | 37 + .../anatomy/src/core/replaceNodeInTree.ts | 10 + ...rt-name.ts => resolveAnatomyExportName.ts} | 0 packages/anatomy/src/core/uid.ts | 6 + .../anatomy/src/core/updateAnatomyNode.ts | 52 + ...ublish.ts => validateAnatomyForPublish.ts} | 22 +- packages/schemas/anatomy.json | 206 ++ ...chema.ts => AnatomyBindingFormatSchema.ts} | 0 ...ding.schema.ts => AnatomyBindingSchema.ts} | 2 +- .../AnatomyCheckWithDiagnosticsSchema.ts | 5 +- .../src/anatomy/AnatomyContract.spec.ts | 2 +- ...etail.schema.ts => AnatomyDetailSchema.ts} | 4 +- ...hema.ts => AnatomyDirectoryEntrySchema.ts} | 4 +- ...ma.ts => AnatomyDraftCreateInputSchema.ts} | 2 +- .../src/anatomy/AnatomyDraftInput.spec.ts | 2 +- ...t.schema.ts => AnatomyDraftInputSchema.ts} | 2 +- ...hema.ts => AnatomyDraftSaveInputSchema.ts} | 2 +- ...yDraft.schema.ts => AnatomyDraftSchema.ts} | 2 +- ...yEntry.schema.ts => AnatomyEntrySchema.ts} | 4 +- ...ry.schema.ts => AnatomyFileEntrySchema.ts} | 6 +- .../AnatomyFunctionExportCheckSchema.ts | 2 +- .../AnatomyFunctionExportRuleSchema.ts | 4 +- ...ut.schema.ts => AnatomyListInputSchema.ts} | 2 +- ...hema.ts => AnatomyNameExpressionSchema.ts} | 0 ...omyNode.schema.ts => AnatomyNodeSchema.ts} | 4 +- ...p.schema.ts => AnatomyOneOfGroupSchema.ts} | 2 +- ...icy.schema.ts => AnatomyPoliciesSchema.ts} | 2 +- ...ema.ts => AnatomyPolicyOverridesSchema.ts} | 0 ....schema.ts => AnatomyPolicyValueSchema.ts} | 0 ...AnatomyPublishedVersionListInputSchema.ts} | 0 ...ity.schema.ts => AnatomyQuantitySchema.ts} | 0 .../AnatomyQueryWithConstraintsSchema.ts | 8 +- ...tatus.schema.ts => AnatomyStatusSchema.ts} | 0 ...re.schema.ts => AnatomyStructureSchema.ts} | 6 +- ...mary.schema.ts => AnatomySummarySchema.ts} | 0 ...sion.schema.ts => AnatomyVersionSchema.ts} | 2 +- packages/schemas/src/anatomy/index.ts | 46 +- 207 files changed, 5048 insertions(+), 1311 deletions(-) create mode 100644 anatomy.coverage.json create mode 100644 anatomy.json mode change 100644 => 100755 apps/anatomy-cli/bin/anatomy.js rename apps/anatomy-cli/bin/{run.js => runEntrypoint.js} (100%) create mode 100644 apps/anatomy-cli/src/AnatomyCliArgumentError.ts create mode 100644 apps/anatomy-cli/src/AnatomyCliExitCode.ts create mode 100644 apps/anatomy-cli/src/AnatomyCliFormatValues.ts create mode 100644 apps/anatomy-cli/src/AnatomyCliUsage.ts create mode 100644 apps/anatomy-cli/src/AnatomyDefinitionFileError.ts create mode 100644 apps/anatomy-cli/src/AnatomyFileTreeError.ts create mode 100644 apps/anatomy-cli/src/AnatomyInstallError.ts create mode 100644 apps/anatomy-cli/src/DefaultAnatomyDefinitionFileName.ts create mode 100644 apps/anatomy-cli/src/DefaultIgnoredNames.ts rename apps/anatomy-cli/src/{analyze-source-exports.ts => analyzeSourceExports.ts} (100%) create mode 100644 apps/anatomy-cli/src/collectFileTree.ts create mode 100644 apps/anatomy-cli/src/collectGitFileTree.ts rename apps/anatomy-cli/src/{collect-source-exports.ts => collectSourceExports.ts} (94%) rename apps/anatomy-cli/src/{install-path.ts => configurePath.ts} (54%) delete mode 100644 apps/anatomy-cli/src/filesystem.ts create mode 100644 apps/anatomy-cli/src/findAnatomyDefinition.ts create mode 100644 apps/anatomy-cli/src/formatAgentCheck.ts create mode 100644 apps/anatomy-cli/src/formatAgentError.ts rename apps/anatomy-cli/src/{format-agent-result.ts => formatAgentQuery.ts} (62%) rename apps/anatomy-cli/src/{format-result.ts => formatHumanResult.ts} (82%) create mode 100644 apps/anatomy-cli/src/formatJsonResult.ts create mode 100644 apps/anatomy-cli/src/getPathPlan.ts create mode 100644 apps/anatomy-cli/src/git-files.spec.ts create mode 100644 apps/anatomy-cli/src/installUsage.ts rename apps/anatomy-cli/src/{cli-arguments.ts => parseCliArguments.ts} (80%) rename apps/anatomy-cli/src/{install-options.ts => parseInstallOptions.ts} (65%) create mode 100644 apps/anatomy-cli/src/posixLauncher.ts create mode 100644 apps/anatomy-cli/src/quoteShell.ts create mode 100644 apps/anatomy-cli/src/readAnatomyDefinition.ts create mode 100644 apps/anatomy-cli/src/repository-contract.spec.ts rename apps/anatomy-cli/src/{cli.ts => runAnatomyCli.ts} (75%) rename apps/anatomy-cli/src/{install.ts => runInstallation.ts} (92%) create mode 100644 apps/anatomy-cli/src/windowsLauncher.ts create mode 100644 apps/anatomy-cli/src/windowsPathScript.ts create mode 100644 apps/docs/src/components/AppBootScreen/BOOT_MOTION.ts create mode 100644 apps/docs/src/components/AppBootScreen/OVERSCAN.ts create mode 100644 apps/docs/src/components/AppBootScreen/TRIANGLE_INRADIUS.ts create mode 100644 apps/docs/src/components/AppBootScreen/TRIANGLE_RADIUS.ts create mode 100644 apps/docs/src/components/AppBootScreen/TRIANGLE_VERTICES.ts rename apps/docs/src/components/AppBootScreen/{boot-geometry.ts => createBootGeometry.ts} (67%) rename apps/docs/src/components/AppBootScreen/{boot-motion.ts => createBootMotion.ts} (71%) create mode 100644 apps/docs/src/components/AppBootScreen/getOpeningScale.ts create mode 100644 apps/docs/src/components/AppBootScreen/getTurnSettleMs.ts create mode 100644 apps/docs/src/components/AppBootScreen/index.ts create mode 100644 apps/docs/src/components/AppBootScreen/polygonPoints.ts create mode 100644 apps/docs/src/components/AppBootScreen/waitForBoot.ts create mode 100644 apps/docs/src/components/StartupHome/TERMINAL_COMMAND.ts create mode 100644 apps/docs/src/components/StartupHome/TERMINAL_DEMO_TIMING.ts create mode 100644 apps/docs/src/components/StartupHome/add.ts rename apps/docs/src/components/StartupHome/{rhombus.ts => createPenroseTiling.ts} (84%) create mode 100644 apps/docs/src/components/StartupHome/createRhombusTiling.ts rename apps/docs/src/components/StartupHome/{terminalDemo.ts => getTerminalDemoFrame.ts} (80%) create mode 100644 apps/docs/src/components/StartupHome/pointsToSvg.ts create mode 100644 apps/docs/src/components/StartupHome/scanRows.tsx create mode 100644 apps/docs/src/components/StartupHome/updateGridPatternHover.tsx create mode 100644 apps/docs/src/components/StartupHome/updateKiteDartHover.tsx create mode 100644 apps/docs/src/components/icons/CODE_PATH_LABELS.ts create mode 100644 apps/docs/src/components/icons/CODE_PATH_MAP.ts create mode 100644 apps/docs/src/components/icons/CODE_PATH_ROUTE.ts delete mode 100644 apps/docs/src/components/icons/codePathMap.ts create mode 100644 apps/docs/src/components/icons/createCodePathDots.ts create mode 100644 apps/docs/src/components/icons/getCodePathPoint.ts create mode 100644 apps/docs/src/components/ui/Button/buttonVariants.tsx create mode 100644 apps/docs/src/components/ui/Card/CardContent.tsx create mode 100644 apps/docs/src/components/ui/Card/CardHeader.tsx create mode 100644 apps/docs/src/components/ui/DropdownMenu/DropdownMenuContent.tsx create mode 100644 apps/docs/src/components/ui/DropdownMenu/DropdownMenuItem.tsx create mode 100644 apps/docs/src/components/ui/DropdownMenu/DropdownMenuSeparator.tsx create mode 100644 apps/docs/src/components/ui/DropdownMenu/DropdownMenuTrigger.tsx rename apps/docs/src/{content.ts => docsEntries.ts} (98%) create mode 100644 apps/docs/src/getDocsEntry.ts create mode 100644 apps/docs/src/lib/PERSISTENT_DETECTION_OPTIONS.ts create mode 100644 apps/docs/src/lib/THEME_PREPAINT_SCRIPT.ts create mode 100644 apps/docs/src/lib/THEME_STORAGE_KEY.ts create mode 100644 apps/docs/src/lib/applySavedLanguage.ts create mode 100644 apps/docs/src/lib/applyTheme.ts rename apps/docs/src/lib/{utils.ts => cn.ts} (100%) create mode 100644 apps/docs/src/lib/getSavedLanguage.ts create mode 100644 apps/docs/src/lib/getSavedTheme.ts rename apps/docs/src/lib/{i18n-server.ts => getServerLanguage.ts} (86%) create mode 100644 apps/docs/src/lib/index.ts create mode 100644 apps/docs/src/lib/languageDetector.ts create mode 100644 apps/docs/src/lib/normalizeLanguage.ts create mode 100644 apps/docs/src/lib/saveTheme.ts delete mode 100644 apps/docs/src/lib/theme.ts rename apps/docs/src/pages/{docs-page.tsx => DocsPage.tsx} (98%) rename apps/docs/src/pages/{home.tsx => HomePage.tsx} (100%) create mode 100644 apps/docs/src/pages/index.ts create mode 100644 packages/anatomy/src/core/AnatomyCheckCode.ts create mode 100644 packages/anatomy/src/core/AnatomyQueryPathError.ts create mode 100644 packages/anatomy/src/core/AnatomySourceAnalysisError.ts create mode 100644 packages/anatomy/src/core/AnatomyValidationCode.ts delete mode 100644 packages/anatomy/src/core/anatomy-tree.ts rename packages/anatomy/src/core/{anatomy-rule-paths.ts => anatomyRulePaths.ts} (100%) create mode 100644 packages/anatomy/src/core/checkAnatomy.ts create mode 100644 packages/anatomy/src/core/cloneEntry.ts create mode 100644 packages/anatomy/src/core/createDirectoryEntry.ts create mode 100644 packages/anatomy/src/core/createEmptyStructure.ts create mode 100644 packages/anatomy/src/core/createFileEntry.ts rename packages/anatomy/src/core/{match-anatomy-name.ts => evaluateName.ts} (100%) create mode 100644 packages/anatomy/src/core/findNodeInTree.ts create mode 100644 packages/anatomy/src/core/groupSiblingEntries.ts create mode 100644 packages/anatomy/src/core/insertAnatomyNode.ts create mode 100644 packages/anatomy/src/core/locateNodeInTree.ts rename packages/anatomy/src/core/{check-anatomy.ts => planAnatomyCheck.ts} (79%) rename packages/anatomy/src/core/{query-anatomy.ts => queryAnatomy.ts} (92%) create mode 100644 packages/anatomy/src/core/removeAnatomyNode.ts create mode 100644 packages/anatomy/src/core/replaceNodeInTree.ts rename packages/anatomy/src/core/{anatomy-export-name.ts => resolveAnatomyExportName.ts} (100%) create mode 100644 packages/anatomy/src/core/uid.ts create mode 100644 packages/anatomy/src/core/updateAnatomyNode.ts rename packages/anatomy/src/core/{validate-anatomy-for-publish.ts => validateAnatomyForPublish.ts} (93%) create mode 100644 packages/schemas/anatomy.json rename packages/schemas/src/anatomy/{AnatomyBindingFormat.schema.ts => AnatomyBindingFormatSchema.ts} (100%) rename packages/schemas/src/anatomy/{AnatomyBinding.schema.ts => AnatomyBindingSchema.ts} (98%) rename packages/schemas/src/anatomy/{AnatomyDetail.schema.ts => AnatomyDetailSchema.ts} (86%) rename packages/schemas/src/anatomy/{AnatomyDirectoryEntry.schema.ts => AnatomyDirectoryEntrySchema.ts} (95%) rename packages/schemas/src/anatomy/{AnatomyDraftCreateInput.schema.ts => AnatomyDraftCreateInputSchema.ts} (79%) rename packages/schemas/src/anatomy/{AnatomyDraftInput.schema.ts => AnatomyDraftInputSchema.ts} (89%) rename packages/schemas/src/anatomy/{AnatomyDraftSaveInput.schema.ts => AnatomyDraftSaveInputSchema.ts} (83%) rename packages/schemas/src/anatomy/{AnatomyDraft.schema.ts => AnatomyDraftSchema.ts} (91%) rename packages/schemas/src/anatomy/{AnatomyEntry.schema.ts => AnatomyEntrySchema.ts} (88%) rename packages/schemas/src/anatomy/{AnatomyFileEntry.schema.ts => AnatomyFileEntrySchema.ts} (91%) rename packages/schemas/src/anatomy/{AnatomyListInput.schema.ts => AnatomyListInputSchema.ts} (90%) rename packages/schemas/src/anatomy/{AnatomyNameExpression.schema.ts => AnatomyNameExpressionSchema.ts} (100%) rename packages/schemas/src/anatomy/{AnatomyNode.schema.ts => AnatomyNodeSchema.ts} (91%) rename packages/schemas/src/anatomy/{AnatomyOneOfGroup.schema.ts => AnatomyOneOfGroupSchema.ts} (98%) rename packages/schemas/src/anatomy/{AnatomyPolicy.schema.ts => AnatomyPoliciesSchema.ts} (90%) rename packages/schemas/src/anatomy/{AnatomyPolicyOverrides.schema.ts => AnatomyPolicyOverridesSchema.ts} (100%) rename packages/schemas/src/anatomy/{AnatomyPolicyValue.schema.ts => AnatomyPolicyValueSchema.ts} (100%) rename packages/schemas/src/anatomy/{AnatomyPublishedVersionListInput.schema.ts => AnatomyPublishedVersionListInputSchema.ts} (100%) rename packages/schemas/src/anatomy/{AnatomyQuantity.schema.ts => AnatomyQuantitySchema.ts} (100%) rename packages/schemas/src/anatomy/{AnatomyStatus.schema.ts => AnatomyStatusSchema.ts} (100%) rename packages/schemas/src/anatomy/{AnatomyStructure.schema.ts => AnatomyStructureSchema.ts} (83%) rename packages/schemas/src/anatomy/{AnatomySummary.schema.ts => AnatomySummarySchema.ts} (100%) rename packages/schemas/src/anatomy/{AnatomyVersion.schema.ts => AnatomyVersionSchema.ts} (90%) diff --git a/.gitignore b/.gitignore index 989cd1b..72f37a9 100644 --- a/.gitignore +++ b/.gitignore @@ -29,5 +29,6 @@ yarn-error.log* # Local agent/editor state .agents/ /docs/ -.github/ +.github/instructions/ +.github/prompts/ .qodo/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8322c5d..a1b3e26 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,3 +11,41 @@ The CLI lives in `apps/anatomy-cli`; reusable tree logic is in `packages/anatomy`; schemas and bundled definitions live in the other two workspace packages. Keep changes self-contained and add or update tests with behavior changes. + +Run `bun run anatomy:check` for a fast whole-repository structure and function +export check. `bun run quality` includes this check and the source-role audit; +the pull-request workflow invokes the same quality command. After building, the +workspace-installed executable also works: `./node_modules/.bin/anatomy . --git-files`. + +The root `anatomy.json` is a reviewed contract, not a snapshot regenerated by +tests. Every project file has an explicit required rule. When adding, moving or +removing files: + +1. Update the corresponding node in `anatomy.json`. Keep structural policies at + `block`; do not introduce a catch-all placeholder to silence a failure. +2. Function modules, hooks and components must export exactly one named function + whose name matches the filename. Use `"exports": { "name": "file_stem" }`. + Type exports do not count. Split additional functions or runtime constants + into their own files and update imports and existing barrels. +3. For a non-function source file, record its exact runtime exports, role and + reason in `anatomy.coverage.json`. Tests validate these declarations. Schemas + export one same-named `*Schema` value with inferred types; barrels only contain + relative wildcard re-exports; tests and process entrypoints expose no runtime + API. Framework-owned modules use explicit reviewed exceptions. +4. For changes inside the CLI source directory or schemas package, update the + matching subtree in `apps/anatomy-cli/anatomies/cli-source.anatomy.json` or + `packages/schemas/anatomy.json` as well. Tests prevent these focused copies + from diverging. `scan:self` and `scan:schemas` use our own contracts, while the + Tellyn catalogue remains a separate set of example conventions. +5. Run `bun run quality`. For documentation-app changes also run + `bun run docs:build:cloudflare` and + `bun --cwd apps/docs scripts/check-cloudflare-build.ts`. + +Git selection includes tracked files and non-ignored new files. Keep project +source and CI files visible to Git; only local state and generated output should +be ignored. Retain temporary plans, reports and demos under the ignored root +`docs/` directory, and never force-add them. Git mode rejects symlinks and +submodules, and does not inventory empty directories. + +The module split keeps named package-level exports available, but internal file +paths have changed. Prefer the package barrels over old source-file deep imports. diff --git a/README.md b/README.md index aeae79c..d3dfec1 100644 --- a/README.md +++ b/README.md @@ -308,18 +308,42 @@ now rejected instead of silently removed; fix spelling or use supported version- rules. Human check output and legacy target/definition flags remain supported. Queries describe declared structure independently of scan exclusions, so `--ignore` -is only accepted for checks. Checks continue to skip symbolic links and default +is only accepted for checks. By default, checks skip symbolic links and default generated directories, including `node_modules` and `dist`; the report lists ignored names. A structural pass only covers the collected tree and executed rules. Run type checks and behavior tests separately. +For repository-wide checks, use `anatomy . --git-files`. This requires Git and +selects tracked files (even when an ignore rule matches them) plus non-ignored +untracked files. It reads the current working tree, so deleted files remain +missing. Git mode includes definition files and does not apply the default +name exclusions; it rejects `--ignore`, symlinks and submodules instead of +silently omitting them. Ignored untracked artifacts and empty directories are +outside this file-based inventory. JSON reports identify `fileSelection: "git"` +and have an empty `ignoredNames` list. + ## Development ```bash +bun run anatomy:check bun run quality bun run build ``` +This repository uses its own workspace CLI. The root `anatomy.json` explicitly +declares every project file across all five workspaces and repository +infrastructure. Function and component modules have one named function export +matching the filename; `router.tsx` and `-RootDocument.tsx` keep the naming +required by the framework through explicit export-name mappings. Schema modules +use `SchemaName.ts` and retain their inferred types beside the schema. + +`anatomy.coverage.json` records the exact exports and reasons for other source +roles: schemas, data, classes, tests, barrels, entrypoints and framework-generated +modules. Repository tests enforce those roles and reject unreviewed exceptions. +`quality` runs the full Anatomy check before type checks, lint, tests and the CLI +build; pull-request CI runs the same command. See `CONTRIBUTING.md` when adding, +moving or removing a file. Local `docs/` artifacts stay outside Git and this scan. + The workspace is self-contained: it has no path or workspace dependency on Daedalus. The implementation was copied from the original Daedalus tooling and its direct Anatomy dependencies. The schemas package contains the complete Anatomy diff --git a/README.zh-CN.md b/README.zh-CN.md index fd6a85d..51e3552 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -221,15 +221,22 @@ bun run anatomy ./packages/services \ 查询完成时所有查询状态均返回退出码 `0`,Agent 应读取 `status` 再决定如何修改。检查仍以 `0` 表示没有阻断项、`1` 表示存在阻断项。运行错误返回 `2`;指定 `--format json` 时,stderr 输出 `operation: "error"` 的 JSON,stdout 不输出成功报告。定义缺失或无效、版本不支持、未知字段和目标不可读都属于错误,不能视为“没有约束”。未知定义字段现在会被拒绝,不再静默移除;需要修正拼写或使用已支持的版本 1 规则。原有人类可读检查输出和目标、定义参数保持可用。 -查询描述声明的结构,不应用扫描忽略规则,因此 `--ignore` 只接受于检查模式。检查仍跳过符号链接以及 `node_modules`、`dist` 等默认生成目录,报告会列出忽略名称。结构检查通过仅覆盖已采集文件树与已执行规则;类型和行为须另行验证。 +查询描述声明的结构,不应用扫描忽略规则,因此 `--ignore` 只接受于检查模式。默认检查跳过符号链接以及 `node_modules`、`dist` 等生成目录,报告会列出忽略名称。结构检查通过仅覆盖已采集文件树与已执行规则;类型和行为须另行验证。 + +检查整个仓库可使用 `anatomy . --git-files`:需要 Git,包含所有已跟踪文件(即使被忽略规则匹配)及未被忽略的新文件。它读取当前工作区,已删除文件仍会报告缺失。此模式包含契约文件,不应用默认名称排除规则,拒绝与 `--ignore` 混用,遇到符号链接或子模块会报错。未跟踪且被忽略的本地产物、空目录不属于此文件清单。JSON 会标明 `fileSelection: "git"`,`ignoredNames` 为空。 ## 开发 ```bash +bun run anatomy:check bun run quality bun run build ``` +本仓库通过 workspace 依赖使用自己的 CLI。根目录的 `anatomy.json` 逐项声明五个工作区及仓库基础设施的全部项目文件;函数和组件模块采用一文件一具名函数,导出名对应文件名。框架要求固定路径的 `router.tsx` 和 `-RootDocument.tsx` 使用显式名称映射。Schema 采用与导出同名的 `*Schema.ts` 文件,派生类型保留在同一文件。 + +其他源码按 Schema、常量、类、测试、barrel、入口及框架生成模块区分;`anatomy.coverage.json` 记录其职责、理由和精确导出列表,仓库测试会验证,不能无说明地跳过约束。`quality` 首先执行全仓 Anatomy 检查,再执行类型、lint、测试和 CLI 构建,PR CI 使用同一入口。新增、移动、删除文件的步骤见 `CONTRIBUTING.md`。本地根目录 `docs/` 产物继续排除在 Git 和扫描范围外。 + 工作区可以独立运行,不存在指向 Daedalus 的路径依赖或工作区依赖。实现复制自原 Daedalus 工具及其直接 Anatomy 依赖。Schema 包包含 CLI 所需的完整 Anatomy 接口,与 Anatomy 无关的 Daedalus 产品领域不属于此独立项目。原始 Daedalus 仓库位于本工作区之外,本项目不会修改它。 ## 发布 diff --git a/anatomy.coverage.json b/anatomy.coverage.json new file mode 100644 index 0000000..8e9d5c8 --- /dev/null +++ b/anatomy.coverage.json @@ -0,0 +1,811 @@ +{ + "schemaVersion": 1, + "exceptions": { + "apps/anatomy-cli/bin/anatomy-cli.js": { + "role": "entrypoint", + "reason": "Executable process entrypoint; intentionally has no public runtime exports.", + "runtimeExports": [] + }, + "apps/anatomy-cli/bin/anatomy.js": { + "role": "entrypoint", + "reason": "Executable process entrypoint; intentionally has no public runtime exports.", + "runtimeExports": [] + }, + "apps/anatomy-cli/src/AnatomyCliArgumentError.ts": { + "role": "class", + "reason": "Dedicated error class; the exported class name must match its filename.", + "runtimeExports": [ + "AnatomyCliArgumentError" + ] + }, + "apps/anatomy-cli/src/AnatomyCliExitCode.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "AnatomyCliExitCode" + ] + }, + "apps/anatomy-cli/src/AnatomyCliFormatValues.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "AnatomyCliFormatValues" + ] + }, + "apps/anatomy-cli/src/AnatomyCliUsage.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "AnatomyCliUsage" + ] + }, + "apps/anatomy-cli/src/AnatomyDefinitionFileError.ts": { + "role": "class", + "reason": "Dedicated error class; the exported class name must match its filename.", + "runtimeExports": [ + "AnatomyDefinitionFileError" + ] + }, + "apps/anatomy-cli/src/AnatomyFileTreeError.ts": { + "role": "class", + "reason": "Dedicated error class; the exported class name must match its filename.", + "runtimeExports": [ + "AnatomyFileTreeError" + ] + }, + "apps/anatomy-cli/src/AnatomyInstallError.ts": { + "role": "class", + "reason": "Dedicated error class; the exported class name must match its filename.", + "runtimeExports": [ + "AnatomyInstallError" + ] + }, + "apps/anatomy-cli/src/DefaultAnatomyDefinitionFileName.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "DefaultAnatomyDefinitionFileName" + ] + }, + "apps/anatomy-cli/src/DefaultIgnoredNames.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "DefaultIgnoredNames" + ] + }, + "apps/anatomy-cli/src/agent-workflow.spec.ts": { + "role": "test", + "reason": "Executable test suite; no public runtime API is exported.", + "runtimeExports": [] + }, + "apps/anatomy-cli/src/analyze-source-exports.spec.ts": { + "role": "test", + "reason": "Executable test suite; no public runtime API is exported.", + "runtimeExports": [] + }, + "apps/anatomy-cli/src/cli-arguments.spec.ts": { + "role": "test", + "reason": "Executable test suite; no public runtime API is exported.", + "runtimeExports": [] + }, + "apps/anatomy-cli/src/cli.spec.ts": { + "role": "test", + "reason": "Executable test suite; no public runtime API is exported.", + "runtimeExports": [] + }, + "apps/anatomy-cli/src/filesystem.spec.ts": { + "role": "test", + "reason": "Executable test suite; no public runtime API is exported.", + "runtimeExports": [] + }, + "apps/anatomy-cli/src/format-agent-result.spec.ts": { + "role": "test", + "reason": "Executable test suite; no public runtime API is exported.", + "runtimeExports": [] + }, + "apps/anatomy-cli/src/function-export-workflow.spec.ts": { + "role": "test", + "reason": "Executable test suite; no public runtime API is exported.", + "runtimeExports": [] + }, + "apps/anatomy-cli/src/git-files.spec.ts": { + "role": "test", + "reason": "Executable test suite; no public runtime API is exported.", + "runtimeExports": [] + }, + "apps/anatomy-cli/src/index.ts": { + "role": "barrel", + "reason": "Public module aggregation; only relative wildcard re-exports are permitted.", + "runtimeExports": [] + }, + "apps/anatomy-cli/src/install-main.ts": { + "role": "entrypoint", + "reason": "Executable process entrypoint; intentionally has no public runtime exports.", + "runtimeExports": [] + }, + "apps/anatomy-cli/src/install.spec.ts": { + "role": "test", + "reason": "Executable test suite; no public runtime API is exported.", + "runtimeExports": [] + }, + "apps/anatomy-cli/src/installUsage.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "installUsage" + ] + }, + "apps/anatomy-cli/src/main.ts": { + "role": "entrypoint", + "reason": "Executable process entrypoint; intentionally has no public runtime exports.", + "runtimeExports": [] + }, + "apps/anatomy-cli/src/posixLauncher.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "posixLauncher" + ] + }, + "apps/anatomy-cli/src/repository-contract.spec.ts": { + "role": "test", + "reason": "Executable test suite; no public runtime API is exported.", + "runtimeExports": [] + }, + "apps/anatomy-cli/src/source-contract.spec.ts": { + "role": "test", + "reason": "Executable test suite; no public runtime API is exported.", + "runtimeExports": [] + }, + "apps/anatomy-cli/src/windowsLauncher.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "windowsLauncher" + ] + }, + "apps/anatomy-cli/src/windowsPathScript.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "windowsPathScript" + ] + }, + "apps/docs/scripts/check-cloudflare-build.ts": { + "role": "entrypoint", + "reason": "Executable process entrypoint; intentionally has no public runtime exports.", + "runtimeExports": [] + }, + "apps/docs/src/components/AppBootScreen/AppBootScreen.lifecycle.test.tsx": { + "role": "test", + "reason": "Executable test suite; no public runtime API is exported.", + "runtimeExports": [] + }, + "apps/docs/src/components/AppBootScreen/AppBootScreen.test.tsx": { + "role": "test", + "reason": "Executable test suite; no public runtime API is exported.", + "runtimeExports": [] + }, + "apps/docs/src/components/AppBootScreen/BOOT_MOTION.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "BOOT_MOTION" + ] + }, + "apps/docs/src/components/AppBootScreen/OVERSCAN.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "OVERSCAN" + ] + }, + "apps/docs/src/components/AppBootScreen/TRIANGLE_INRADIUS.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "TRIANGLE_INRADIUS" + ] + }, + "apps/docs/src/components/AppBootScreen/TRIANGLE_RADIUS.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "TRIANGLE_RADIUS" + ] + }, + "apps/docs/src/components/AppBootScreen/TRIANGLE_VERTICES.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "TRIANGLE_VERTICES" + ] + }, + "apps/docs/src/components/AppBootScreen/index.ts": { + "role": "barrel", + "reason": "Public module aggregation; only relative wildcard re-exports are permitted.", + "runtimeExports": [] + }, + "apps/docs/src/components/LanguageSwitcher/index.ts": { + "role": "barrel", + "reason": "Public module aggregation; only relative wildcard re-exports are permitted.", + "runtimeExports": [] + }, + "apps/docs/src/components/MonoBlockCanvas/index.ts": { + "role": "barrel", + "reason": "Public module aggregation; only relative wildcard re-exports are permitted.", + "runtimeExports": [] + }, + "apps/docs/src/components/MonoLaunchHero/index.ts": { + "role": "barrel", + "reason": "Public module aggregation; only relative wildcard re-exports are permitted.", + "runtimeExports": [] + }, + "apps/docs/src/components/PublicLayout/index.ts": { + "role": "barrel", + "reason": "Public module aggregation; only relative wildcard re-exports are permitted.", + "runtimeExports": [] + }, + "apps/docs/src/components/StartupHome/StartupTerminalCase.test.tsx": { + "role": "test", + "reason": "Executable test suite; no public runtime API is exported.", + "runtimeExports": [] + }, + "apps/docs/src/components/StartupHome/TERMINAL_COMMAND.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "TERMINAL_COMMAND" + ] + }, + "apps/docs/src/components/StartupHome/TERMINAL_DEMO_TIMING.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "TERMINAL_DEMO_TIMING" + ] + }, + "apps/docs/src/components/StartupHome/index.ts": { + "role": "barrel", + "reason": "Public module aggregation; only relative wildcard re-exports are permitted.", + "runtimeExports": [] + }, + "apps/docs/src/components/StartupHome/scanRows.tsx": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "scanRows" + ] + }, + "apps/docs/src/components/icons/CODE_PATH_LABELS.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "CODE_PATH_LABELS" + ] + }, + "apps/docs/src/components/icons/CODE_PATH_MAP.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "CODE_PATH_MAP" + ] + }, + "apps/docs/src/components/icons/CODE_PATH_ROUTE.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "CODE_PATH_ROUTE" + ] + }, + "apps/docs/src/components/icons/index.ts": { + "role": "barrel", + "reason": "Public module aggregation; only relative wildcard re-exports are permitted.", + "runtimeExports": [] + }, + "apps/docs/src/components/ui/Badge/index.ts": { + "role": "barrel", + "reason": "Public module aggregation; only relative wildcard re-exports are permitted.", + "runtimeExports": [] + }, + "apps/docs/src/components/ui/Button/buttonVariants.tsx": { + "role": "framework", + "reason": "CVA returns a callable style variant factory; its implementation belongs to the framework.", + "runtimeExports": [ + "buttonVariants" + ] + }, + "apps/docs/src/components/ui/Button/index.ts": { + "role": "barrel", + "reason": "Public module aggregation; only relative wildcard re-exports are permitted.", + "runtimeExports": [] + }, + "apps/docs/src/components/ui/Card/index.ts": { + "role": "barrel", + "reason": "Public module aggregation; only relative wildcard re-exports are permitted.", + "runtimeExports": [] + }, + "apps/docs/src/components/ui/DropdownMenu/DropdownMenu.tsx": { + "role": "framework", + "reason": "Base UI component alias preserves the framework component identity and ref behavior.", + "runtimeExports": [ + "DropdownMenu" + ] + }, + "apps/docs/src/components/ui/DropdownMenu/DropdownMenuTrigger.tsx": { + "role": "framework", + "reason": "Base UI component alias preserves the framework component identity and ref behavior.", + "runtimeExports": [ + "DropdownMenuTrigger" + ] + }, + "apps/docs/src/components/ui/DropdownMenu/index.ts": { + "role": "barrel", + "reason": "Public module aggregation; only relative wildcard re-exports are permitted.", + "runtimeExports": [] + }, + "apps/docs/src/docsEntries.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "docsEntries" + ] + }, + "apps/docs/src/lib/PERSISTENT_DETECTION_OPTIONS.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "PERSISTENT_DETECTION_OPTIONS" + ] + }, + "apps/docs/src/lib/THEME_PREPAINT_SCRIPT.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "THEME_PREPAINT_SCRIPT" + ] + }, + "apps/docs/src/lib/THEME_STORAGE_KEY.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "THEME_STORAGE_KEY" + ] + }, + "apps/docs/src/lib/i18n.ts": { + "role": "framework", + "reason": "Shared initialized i18next instance; consumers depend on the default singleton export.", + "runtimeExports": [ + "default" + ] + }, + "apps/docs/src/lib/index.ts": { + "role": "barrel", + "reason": "Public module aggregation; only relative wildcard re-exports are permitted.", + "runtimeExports": [] + }, + "apps/docs/src/lib/languageDetector.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "languageDetector" + ] + }, + "apps/docs/src/pages/index.ts": { + "role": "barrel", + "reason": "Public module aggregation; only relative wildcard re-exports are permitted.", + "runtimeExports": [] + }, + "apps/docs/src/payload-types.ts": { + "role": "generated", + "reason": "Framework-generated declarations or registrations; preserve the generator-owned export layout.", + "runtimeExports": [] + }, + "apps/docs/src/payload.config.ts": { + "role": "framework", + "reason": "Payload requires the default configuration factory result.", + "runtimeExports": [ + "default" + ] + }, + "apps/docs/src/routeTree.gen.ts": { + "role": "generated", + "reason": "Framework-generated declarations or registrations; preserve the generator-owned export layout.", + "runtimeExports": [ + "routeTree" + ] + }, + "apps/docs/src/routes/$.tsx": { + "role": "framework", + "reason": "TanStack/Payload route or server factory contract fixes the export names and module placement.", + "runtimeExports": [ + "Route" + ] + }, + "apps/docs/src/routes/__root.tsx": { + "role": "framework", + "reason": "TanStack/Payload route or server factory contract fixes the export names and module placement.", + "runtimeExports": [ + "Route" + ] + }, + "apps/docs/src/routes/_payload.admin.$.tsx": { + "role": "framework", + "reason": "TanStack/Payload route or server factory contract fixes the export names and module placement.", + "runtimeExports": [ + "Route" + ] + }, + "apps/docs/src/routes/_payload.admin.index.tsx": { + "role": "framework", + "reason": "TanStack/Payload route or server factory contract fixes the export names and module placement.", + "runtimeExports": [ + "Route" + ] + }, + "apps/docs/src/routes/_payload.api.$.ts": { + "role": "framework", + "reason": "TanStack/Payload route or server factory contract fixes the export names and module placement.", + "runtimeExports": [ + "Route" + ] + }, + "apps/docs/src/routes/_payload.tsx": { + "role": "framework", + "reason": "TanStack/Payload route or server factory contract fixes the export names and module placement.", + "runtimeExports": [ + "Route" + ] + }, + "apps/docs/src/routes/_payload/importMap.js": { + "role": "generated", + "reason": "Framework-generated declarations or registrations; preserve the generator-owned export layout.", + "runtimeExports": [ + "importMap" + ] + }, + "apps/docs/src/routes/_payload/server.functions.ts": { + "role": "framework", + "reason": "TanStack/Payload route or server factory contract fixes the export names and module placement.", + "runtimeExports": [ + "getLayoutDataFn", + "loadAdminPageRSC", + "serverFunctionHandler" + ] + }, + "apps/docs/src/routes/docs.$slug.tsx": { + "role": "framework", + "reason": "TanStack/Payload route or server factory contract fixes the export names and module placement.", + "runtimeExports": [ + "Route" + ] + }, + "apps/docs/src/routes/docs.index.tsx": { + "role": "framework", + "reason": "TanStack/Payload route or server factory contract fixes the export names and module placement.", + "runtimeExports": [ + "Route" + ] + }, + "apps/docs/src/routes/docs.tsx": { + "role": "framework", + "reason": "TanStack/Payload route or server factory contract fixes the export names and module placement.", + "runtimeExports": [ + "Route" + ] + }, + "apps/docs/src/routes/index.tsx": { + "role": "framework", + "reason": "TanStack/Payload route or server factory contract fixes the export names and module placement.", + "runtimeExports": [ + "Route" + ] + }, + "apps/docs/vite.config.ts": { + "role": "framework", + "reason": "Vite requires a default build configuration factory result.", + "runtimeExports": [ + "default" + ] + }, + "apps/docs/vitest.config.ts": { + "role": "framework", + "reason": "Vitest requires a default test configuration factory result.", + "runtimeExports": [ + "default" + ] + }, + "packages/anatomy-cli-config/src/anatomies.spec.ts": { + "role": "test", + "reason": "Executable test suite; no public runtime API is exported.", + "runtimeExports": [] + }, + "packages/anatomy/src/core/AnatomyCheckCode.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "AnatomyCheckCode" + ] + }, + "packages/anatomy/src/core/AnatomyQueryPathError.ts": { + "role": "class", + "reason": "Dedicated error class; the exported class name must match its filename.", + "runtimeExports": [ + "AnatomyQueryPathError" + ] + }, + "packages/anatomy/src/core/AnatomySourceAnalysisError.ts": { + "role": "class", + "reason": "Dedicated error class; the exported class name must match its filename.", + "runtimeExports": [ + "AnatomySourceAnalysisError" + ] + }, + "packages/anatomy/src/core/AnatomyValidationCode.ts": { + "role": "data", + "reason": "Dedicated named constant or data definition matching the filename; direct function exports are forbidden.", + "runtimeExports": [ + "AnatomyValidationCode" + ] + }, + "packages/anatomy/src/core/ResolvedAnatomyPolicy.ts": { + "role": "types", + "reason": "Compile-time support contract; no runtime exports are permitted.", + "runtimeExports": [] + }, + "packages/anatomy/src/core/anatomy-tree.spec.ts": { + "role": "test", + "reason": "Executable test suite; no public runtime API is exported.", + "runtimeExports": [] + }, + "packages/anatomy/src/core/check-anatomy.spec.ts": { + "role": "test", + "reason": "Executable test suite; no public runtime API is exported.", + "runtimeExports": [] + }, + "packages/anatomy/src/core/function-export.spec.ts": { + "role": "test", + "reason": "Executable test suite; no public runtime API is exported.", + "runtimeExports": [] + }, + "packages/anatomy/src/core/index.ts": { + "role": "barrel", + "reason": "Public module aggregation; only relative wildcard re-exports are permitted.", + "runtimeExports": [] + }, + "packages/anatomy/src/core/query-anatomy.spec.ts": { + "role": "test", + "reason": "Executable test suite; no public runtime API is exported.", + "runtimeExports": [] + }, + "packages/anatomy/src/index.ts": { + "role": "barrel", + "reason": "Public module aggregation; only relative wildcard re-exports are permitted.", + "runtimeExports": [] + }, + "packages/schemas/src/anatomy/AnatomyBindingFormatSchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyBindingFormatSchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyBindingSchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyBindingSchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyCheckWithDiagnosticsSchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyCheckWithDiagnosticsSchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyContract.spec.ts": { + "role": "test", + "reason": "Executable test suite; no public runtime API is exported.", + "runtimeExports": [] + }, + "packages/schemas/src/anatomy/AnatomyDetailSchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyDetailSchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyDirectoryEntrySchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyDirectoryEntrySchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyDraftCreateInputSchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyDraftCreateInputSchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyDraftInput.spec.ts": { + "role": "test", + "reason": "Executable test suite; no public runtime API is exported.", + "runtimeExports": [] + }, + "packages/schemas/src/anatomy/AnatomyDraftInputSchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyDraftInputSchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyDraftSaveInputSchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyDraftSaveInputSchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyDraftSchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyDraftSchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyEntrySchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyEntrySchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyFileEntrySchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyFileEntrySchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyFunctionExportCheckSchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyFunctionExportCheckSchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyFunctionExportRuleSchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyFunctionExportRuleSchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyListInputSchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyListInputSchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyNameExpressionSchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyNameExpressionSchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyNodeSchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyNodeSchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyOneOfGroupSchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyOneOfGroupSchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyPoliciesSchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyPoliciesSchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyPolicyOverridesSchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyPolicyOverridesSchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyPolicyValueSchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyPolicyValueSchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyPublishedVersionListInputSchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyPublishedVersionListInputSchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyQuantitySchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyQuantitySchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyQueryWithConstraintsSchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyQueryWithConstraintsSchema" + ] + }, + "packages/schemas/src/anatomy/AnatomySourceExportsSchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomySourceExportsSchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyStatusSchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyStatusSchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyStructureSchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyStructureSchema" + ] + }, + "packages/schemas/src/anatomy/AnatomySummarySchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomySummarySchema" + ] + }, + "packages/schemas/src/anatomy/AnatomyVersionSchema.ts": { + "role": "schema", + "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", + "runtimeExports": [ + "AnatomyVersionSchema" + ] + }, + "packages/schemas/src/anatomy/index.ts": { + "role": "barrel", + "reason": "Public module aggregation; only relative wildcard re-exports are permitted.", + "runtimeExports": [] + }, + "packages/schemas/src/index.ts": { + "role": "barrel", + "reason": "Public module aggregation; only relative wildcard re-exports are permitted.", + "runtimeExports": [] + }, + "vitest.config.ts": { + "role": "framework", + "reason": "Vitest requires a default test configuration factory result.", + "runtimeExports": [ + "default" + ] + } + } +} diff --git a/anatomy.json b/anatomy.json new file mode 100644 index 0000000..bda3ad9 --- /dev/null +++ b/anatomy.json @@ -0,0 +1,1998 @@ +{ + "name": "Anatomy repository", + "purpose": "Strict repository structure and function export contracts for all Git-visible files. Run anatomy . --git-files. Non-function source roles are reviewed in anatomy.coverage.json and verified by repository-contract.spec.ts.", + "structure": { + "schemaVersion": 1, + "defaultPolicies": { + "missingRequired": "block", + "unexpectedEntry": "block", + "nameMismatch": "block", + "nestingMismatch": "block" + }, + "root": { + "children": [ + { + "kind": "directory", + "name": { "type": "literal", "value": ".github" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "directory", + "name": { "type": "literal", "value": "workflows" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "ci.yml" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "deploy-docs.yml" }, + "quantity": "exactly_one" + } + ] + } + ] + }, + { + "kind": "file", + "name": { "type": "literal", "value": ".gitignore" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "CONTRIBUTING.md" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "LICENSE" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "README.md" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "README.zh-CN.md" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "anatomy.coverage.json" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "anatomy.json" }, + "quantity": "exactly_one" + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "apps" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "directory", + "name": { "type": "literal", "value": "anatomy-cli" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "directory", + "name": { "type": "literal", "value": "anatomies" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "cli-source.anatomy.json" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "drizzle-table-files.anatomy.json" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "service-files.anatomy.json" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "bin" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "anatomy-cli.js" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "anatomy.js" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "runEntrypoint.js" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + } + ] + }, + { + "kind": "file", + "name": { "type": "literal", "value": "package.json" }, + "quantity": "exactly_one" + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "src" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyCliArgumentError.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyCliExitCode.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyCliFormatValues.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyCliUsage.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyDefinitionFileError.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyFileTreeError.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyInstallError.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "DefaultAnatomyDefinitionFileName.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "DefaultIgnoredNames.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "agent-workflow.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "analyze-source-exports.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "analyzeSourceExports.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "cli-arguments.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "cli.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "collectFileTree.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "collectGitFileTree.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "collectSourceExports.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "configurePath.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "filesystem.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "findAnatomyDefinition.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "format-agent-result.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "formatAgentCheck.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "formatAgentError.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "formatAgentQuery.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "formatHumanResult.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "formatJsonResult.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "function-export-workflow.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "getPathPlan.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "git-files.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "index.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "install-main.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "install.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "installUsage.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "main.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "parseCliArguments.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "parseInstallOptions.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "posixLauncher.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "quoteShell.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "readAnatomyDefinition.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "repository-contract.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "runAnatomyCli.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "runInstallation.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "source-contract.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "windowsLauncher.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "windowsPathScript.ts" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "file", + "name": { "type": "literal", "value": "tsconfig.json" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "docs" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": ".env.example" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "README.md" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "README.zh-CN.md" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "package.json" }, + "quantity": "exactly_one" + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "plans" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "2026-09-01-galaxy-hero-design.md" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "2026-09-01-placeholder-binding-design.md" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "2026-09-01-tailwind-shadcn-design.md" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "2026-09-01-tanstack-docs-design.md" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "2026-09-02-aceternity-startup-home-design.md" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "2026-09-02-home-redesign-design.md" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "2026-09-02-monolaunch-home-redesign-design.md" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "public" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "_redirects" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "logo.svg" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "scripts" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "check-cloudflare-build.ts" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "src" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "directory", + "name": { "type": "literal", "value": "components" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "directory", + "name": { "type": "literal", "value": "AppBootScreen" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "AppBootScreen.lifecycle.test.tsx" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AppBootScreen.test.tsx" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AppBootScreen.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "BOOT_MOTION.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "OVERSCAN.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "TRIANGLE_INRADIUS.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "TRIANGLE_RADIUS.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "TRIANGLE_VERTICES.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "createBootGeometry.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "createBootMotion.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "getOpeningScale.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "getTurnSettleMs.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "index.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "polygonPoints.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "waitForBoot.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + } + ] + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "LanguageSwitcher" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "LanguageSwitcher.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "index.ts" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "MonoBlockCanvas" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "MonoBlockCanvas.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "index.ts" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "MonoLaunchHero" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "MonoLaunchHero.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "index.ts" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "PublicLayout" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "PublicLayout.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "index.ts" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "StartupHome" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "KiteDartPattern.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "RhombusPattern.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "StartupCiFileTree.css" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "StartupCiFileTree.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "StartupCiSection.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "StartupCta.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "StartupFooter.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "StartupGridBackground.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "StartupHeader.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "StartupHero.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "StartupHome.temp.json" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "StartupHome.temp.md" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "StartupHome.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "StartupScanSection.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "StartupTerminalCase.css" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "StartupTerminalCase.test.tsx" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "StartupTerminalCase.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "StructureScanPreview.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "StructureTreeRow.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "TERMINAL_COMMAND.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "TERMINAL_DEMO_TIMING.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "add.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "createPenroseTiling.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "createRhombusTiling.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "getTerminalDemoFrame.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "index.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "pointsToSvg.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "scanRows.tsx" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "updateGridPatternHover.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "updateKiteDartHover.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "useTerminalDemo.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + } + ] + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "icons" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "CODE_PATH_LABELS.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "CODE_PATH_MAP.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "CODE_PATH_ROUTE.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "CodePathMapIcon.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "createCodePathDots.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "getCodePathPoint.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "index.ts" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "ui" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "directory", + "name": { "type": "literal", "value": "Badge" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "Badge.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "index.ts" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "Button" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "Button.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "buttonVariants.tsx" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "index.ts" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "Card" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "Card.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "CardContent.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "CardHeader.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "index.ts" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "DropdownMenu" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "DropdownMenu.tsx" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "DropdownMenuContent.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "DropdownMenuItem.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "DropdownMenuSeparator.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "DropdownMenuTrigger.tsx" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "index.ts" }, + "quantity": "exactly_one" + } + ] + } + ] + } + ] + }, + { + "kind": "file", + "name": { "type": "literal", "value": "docsEntries.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "getDocsEntry.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "lib" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "PERSISTENT_DETECTION_OPTIONS.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "THEME_PREPAINT_SCRIPT.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "THEME_STORAGE_KEY.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "applySavedLanguage.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "applyTheme.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "cn.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "getSavedLanguage.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "getSavedTheme.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "getServerLanguage.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "i18n.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "index.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "languageDetector.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "normalizeLanguage.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "saveTheme.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + } + ] + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "locales" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "en.json" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "zh.json" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "pages" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "DocsPage.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "HomePage.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "index.ts" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "file", + "name": { "type": "literal", "value": "payload-types.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "payload.config.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "routeTree.gen.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "router.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": { "type": "literal", "value": "getRouter" } + } + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "routes" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "$.tsx" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "-RootDocument.tsx" }, + "quantity": "exactly_one", + "exports": { + "name": { "type": "literal", "value": "RootDocument" } + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "__root.tsx" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "_payload.admin.$.tsx" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "_payload.admin.index.tsx" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "_payload.api.$.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "_payload.tsx" }, + "quantity": "exactly_one" + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "_payload" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "importMap.js" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "server.functions.ts" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "file", + "name": { "type": "literal", "value": "docs.$slug.tsx" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "docs.index.tsx" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "docs.tsx" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "index.tsx" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "file", + "name": { "type": "literal", "value": "styles.css" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "file", + "name": { "type": "literal", "value": "tsconfig.json" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "vite.config.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "vitest.config.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "wrangler.jsonc" }, + "quantity": "exactly_one" + } + ] + } + ] + }, + { + "kind": "file", + "name": { "type": "literal", "value": "bun.lock" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "install.ps1" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "install.sh" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "package.json" }, + "quantity": "exactly_one" + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "packages" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "directory", + "name": { "type": "literal", "value": "anatomy-cli-config" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "package.json" }, + "quantity": "exactly_one" + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "src" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "anatomies.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "anatomies" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "dao.anatomy.json" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "drizzle-relation.anatomy.json" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "drizzle-table.anatomy.json" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "mobile-screen.anatomy.json" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "repository.anatomy.json" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "schemas.anatomy.json" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "service.anatomy.json" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "trpc-router.anatomy.json" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "zod-schema.anatomy.json" }, + "quantity": "exactly_one" + } + ] + } + ] + }, + { + "kind": "file", + "name": { "type": "literal", "value": "tsconfig.json" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "anatomy" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "package.json" }, + "quantity": "exactly_one" + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "src" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "directory", + "name": { "type": "literal", "value": "core" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyCheckCode.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyQueryPathError.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomySourceAnalysisError.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyValidationCode.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "ResolvedAnatomyPolicy.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "anatomy-tree.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "anatomyRulePaths.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "check-anatomy.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "checkAnatomy.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "cloneEntry.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "createDirectoryEntry.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "createEmptyAnatomyDraft.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "createEmptyStructure.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "createFileEntry.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "evaluateName.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "findNodeInTree.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "function-export.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "groupSiblingEntries.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "index.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "insertAnatomyNode.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "locateNodeInTree.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "planAnatomyCheck.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "query-anatomy.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "queryAnatomy.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "removeAnatomyNode.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "replaceNodeInTree.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "resolveAnatomyExportName.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "resolveAnatomyPolicies.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "uid.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "updateAnatomyNode.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "validateAnatomyForPublish.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + } + ] + }, + { + "kind": "file", + "name": { "type": "literal", "value": "index.ts" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "file", + "name": { "type": "literal", "value": "tsconfig.json" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "schemas" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "anatomy.json" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "package.json" }, + "quantity": "exactly_one" + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "src" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "directory", + "name": { "type": "literal", "value": "anatomy" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyBindingFormatSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyBindingSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyCheckWithDiagnosticsSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyContract.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyDetailSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyDirectoryEntrySchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyDraftCreateInputSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyDraftInput.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyDraftInputSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyDraftSaveInputSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyDraftSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyEntrySchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyFileEntrySchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyFunctionExportCheckSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyFunctionExportRuleSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyListInputSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyNameExpressionSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyNodeSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyOneOfGroupSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyPoliciesSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyPolicyOverridesSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyPolicyValueSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyPublishedVersionListInputSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyQuantitySchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyQueryWithConstraintsSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomySourceExportsSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyStatusSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyStructureSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomySummarySchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyVersionSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "index.ts" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "file", + "name": { "type": "literal", "value": "index.ts" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "file", + "name": { "type": "literal", "value": "tsconfig.json" }, + "quantity": "exactly_one" + } + ] + } + ] + }, + { + "kind": "file", + "name": { "type": "literal", "value": "tsconfig.json" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "vitest.config.ts" }, + "quantity": "exactly_one" + } + ] + } + } +} diff --git a/apps/anatomy-cli/anatomies/cli-source.anatomy.json b/apps/anatomy-cli/anatomies/cli-source.anatomy.json index 254843f..657e1f4 100644 --- a/apps/anatomy-cli/anatomies/cli-source.anatomy.json +++ b/apps/anatomy-cli/anatomies/cli-source.anatomy.json @@ -1,6 +1,6 @@ { "name": "Anatomy CLI source modules", - "purpose": "A concrete Anatomy case for the apps/anatomy-cli/src directory. Keep the CLI entrypoint, adapters, formatters, and their tests explicit so structural changes are intentional.", + "purpose": "Focused copy of the repository contract for the CLI source directory; tests prevent divergence.", "structure": { "schemaVersion": 1, "defaultPolicies": { @@ -13,47 +13,47 @@ "children": [ { "kind": "file", - "name": { "type": "literal", "value": "index.ts" }, + "name": { "type": "literal", "value": "AnatomyCliArgumentError.ts" }, "quantity": "exactly_one" }, { "kind": "file", - "name": { "type": "literal", "value": "main.ts" }, + "name": { "type": "literal", "value": "AnatomyCliExitCode.ts" }, "quantity": "exactly_one" }, { "kind": "file", - "name": { "type": "literal", "value": "cli.ts" }, + "name": { "type": "literal", "value": "AnatomyCliFormatValues.ts" }, "quantity": "exactly_one" }, { "kind": "file", - "name": { "type": "literal", "value": "cli.spec.ts" }, + "name": { "type": "literal", "value": "AnatomyCliUsage.ts" }, "quantity": "exactly_one" }, { "kind": "file", - "name": { "type": "literal", "value": "cli-arguments.ts" }, + "name": { "type": "literal", "value": "AnatomyDefinitionFileError.ts" }, "quantity": "exactly_one" }, { "kind": "file", - "name": { "type": "literal", "value": "cli-arguments.spec.ts" }, + "name": { "type": "literal", "value": "AnatomyFileTreeError.ts" }, "quantity": "exactly_one" }, { "kind": "file", - "name": { "type": "literal", "value": "filesystem.ts" }, + "name": { "type": "literal", "value": "AnatomyInstallError.ts" }, "quantity": "exactly_one" }, { "kind": "file", - "name": { "type": "literal", "value": "filesystem.spec.ts" }, + "name": { "type": "literal", "value": "DefaultAnatomyDefinitionFileName.ts" }, "quantity": "exactly_one" }, { "kind": "file", - "name": { "type": "literal", "value": "format-result.ts" }, + "name": { "type": "literal", "value": "DefaultIgnoredNames.ts" }, "quantity": "exactly_one" }, { @@ -63,9 +63,72 @@ }, { "kind": "file", - "name": { "type": "literal", "value": "format-agent-result.ts" }, + "name": { "type": "literal", "value": "analyze-source-exports.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "analyzeSourceExports.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "cli-arguments.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "cli.spec.ts" }, "quantity": "exactly_one" }, + { + "kind": "file", + "name": { "type": "literal", "value": "collectFileTree.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "collectGitFileTree.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "collectSourceExports.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "configurePath.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "filesystem.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "findAnatomyDefinition.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, { "kind": "file", "name": { "type": "literal", "value": "format-agent-result.spec.ts" }, @@ -73,22 +136,70 @@ }, { "kind": "file", - "name": { "type": "literal", "value": "source-contract.spec.ts" }, + "name": { "type": "literal", "value": "formatAgentCheck.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "formatAgentError.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "formatAgentQuery.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "formatHumanResult.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "formatJsonResult.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "function-export-workflow.spec.ts" }, "quantity": "exactly_one" }, { "kind": "file", - "name": { "type": "literal", "value": "install-main.ts" }, + "name": { "type": "literal", "value": "getPathPlan.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "git-files.spec.ts" }, "quantity": "exactly_one" }, { "kind": "file", - "name": { "type": "literal", "value": "install-options.ts" }, + "name": { "type": "literal", "value": "index.ts" }, "quantity": "exactly_one" }, { "kind": "file", - "name": { "type": "literal", "value": "install-path.ts" }, + "name": { "type": "literal", "value": "install-main.ts" }, "quantity": "exactly_one" }, { @@ -98,29 +209,85 @@ }, { "kind": "file", - "name": { "type": "literal", "value": "install.ts" }, + "name": { "type": "literal", "value": "installUsage.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "main.ts" }, "quantity": "exactly_one" }, { "kind": "file", - "name": { "type": "literal", "value": "analyze-source-exports.ts" }, + "name": { "type": "literal", "value": "parseCliArguments.ts" }, "quantity": "exactly_one", - "exports": { "name": { "type": "literal", "value": "analyzeSourceExports" } } + "exports": { + "name": "file_stem" + } }, { "kind": "file", - "name": { "type": "literal", "value": "collect-source-exports.ts" }, + "name": { "type": "literal", "value": "parseInstallOptions.ts" }, "quantity": "exactly_one", - "exports": { "name": { "type": "literal", "value": "collectSourceExports" } } + "exports": { + "name": "file_stem" + } }, { "kind": "file", - "name": { "type": "literal", "value": "analyze-source-exports.spec.ts" }, + "name": { "type": "literal", "value": "posixLauncher.ts" }, "quantity": "exactly_one" }, { "kind": "file", - "name": { "type": "literal", "value": "function-export-workflow.spec.ts" }, + "name": { "type": "literal", "value": "quoteShell.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "readAnatomyDefinition.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "repository-contract.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "runAnatomyCli.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "runInstallation.ts" }, + "quantity": "exactly_one", + "exports": { + "name": "file_stem" + } + }, + { + "kind": "file", + "name": { "type": "literal", "value": "source-contract.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "windowsLauncher.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "windowsPathScript.ts" }, "quantity": "exactly_one" } ] diff --git a/apps/anatomy-cli/bin/anatomy-cli.js b/apps/anatomy-cli/bin/anatomy-cli.js index aa511c8..b0c7a6e 100755 --- a/apps/anatomy-cli/bin/anatomy-cli.js +++ b/apps/anatomy-cli/bin/anatomy-cli.js @@ -1,6 +1,6 @@ #!/usr/bin/env node -import { runEntrypoint } from "./run.js"; +import { runEntrypoint } from "./runEntrypoint.js"; const args = process.argv.slice(2); const installFlags = ["--install", "--prefix", "--no-modify-path", "--uninstall"]; diff --git a/apps/anatomy-cli/bin/anatomy.js b/apps/anatomy-cli/bin/anatomy.js old mode 100644 new mode 100755 index b1da967..1726ebb --- a/apps/anatomy-cli/bin/anatomy.js +++ b/apps/anatomy-cli/bin/anatomy.js @@ -1,5 +1,5 @@ #!/usr/bin/env node -import { runEntrypoint } from "./run.js"; +import { runEntrypoint } from "./runEntrypoint.js"; await runEntrypoint("main"); diff --git a/apps/anatomy-cli/bin/run.js b/apps/anatomy-cli/bin/runEntrypoint.js similarity index 100% rename from apps/anatomy-cli/bin/run.js rename to apps/anatomy-cli/bin/runEntrypoint.js diff --git a/apps/anatomy-cli/package.json b/apps/anatomy-cli/package.json index 673914f..98593e3 100644 --- a/apps/anatomy-cli/package.json +++ b/apps/anatomy-cli/package.json @@ -37,12 +37,12 @@ "build": "bun build src/main.ts --target=node --outfile=dist/main.js && bun build src/index.ts --target=node --outfile=dist/index.js && bun build src/install-main.ts --target=node --outfile=dist/install-main.js", "dev": "bun --watch src/main.ts", "start": "bun src/main.ts", - "scan:self": "bun src/main.ts ../../packages/schemas/src/anatomy --definition ../../packages/anatomy-cli-config/src/anatomies/zod-schema.anatomy.json", - "scan:schemas": "bun src/main.ts ../../packages/schemas --definition ../../packages/anatomy-cli-config/src/anatomies/schemas.anatomy.json", + "scan:self": "bun src/main.ts ../.. --git-files", + "scan:schemas": "bun src/main.ts ../../packages/schemas --git-files", "check-types": "tsc --noEmit", "lint": "oxlint src/", "test": "vitest run", - "quality": "bun run check-types && bun run lint && bun run test && bun run build", + "quality": "bun run scan:self && bun run check-types && bun run lint && bun run test && bun run build", "prepack": "bun run build" }, "engines": { diff --git a/apps/anatomy-cli/src/AnatomyCliArgumentError.ts b/apps/anatomy-cli/src/AnatomyCliArgumentError.ts new file mode 100644 index 0000000..9925a4e --- /dev/null +++ b/apps/anatomy-cli/src/AnatomyCliArgumentError.ts @@ -0,0 +1,6 @@ +export class AnatomyCliArgumentError extends Error { + constructor(message: string) { + super(message); + this.name = "AnatomyCliArgumentError"; + } +} diff --git a/apps/anatomy-cli/src/AnatomyCliExitCode.ts b/apps/anatomy-cli/src/AnatomyCliExitCode.ts new file mode 100644 index 0000000..cc60c6d --- /dev/null +++ b/apps/anatomy-cli/src/AnatomyCliExitCode.ts @@ -0,0 +1,5 @@ +export const AnatomyCliExitCode = { + success: 0, + blocked: 1, + operationalError: 2, +} as const; diff --git a/apps/anatomy-cli/src/AnatomyCliFormatValues.ts b/apps/anatomy-cli/src/AnatomyCliFormatValues.ts new file mode 100644 index 0000000..7437209 --- /dev/null +++ b/apps/anatomy-cli/src/AnatomyCliFormatValues.ts @@ -0,0 +1 @@ +export const AnatomyCliFormatValues = ["human", "json"] as const; diff --git a/apps/anatomy-cli/src/AnatomyCliUsage.ts b/apps/anatomy-cli/src/AnatomyCliUsage.ts new file mode 100644 index 0000000..7064f0b --- /dev/null +++ b/apps/anatomy-cli/src/AnatomyCliUsage.ts @@ -0,0 +1,15 @@ +export const AnatomyCliUsage = [ + "Usage: anatomy [target] [options]", + "", + "Arguments:", + " target Directory to check (default: current directory)", + "", + "Options:", + " -d, --definition Anatomy JSON (default: nearest anatomy.json)", + " -t, --target Alternate form of the target argument", + " --format human or json (default: human)", + " --query Query constraints relative to target (path may not exist)", + " --git-files Check tracked and non-ignored untracked files (requires Git)", + " --ignore Comma-separated names; may be repeated", + " -h, --help Show this help", +].join("\n"); diff --git a/apps/anatomy-cli/src/AnatomyDefinitionFileError.ts b/apps/anatomy-cli/src/AnatomyDefinitionFileError.ts new file mode 100644 index 0000000..119f2c8 --- /dev/null +++ b/apps/anatomy-cli/src/AnatomyDefinitionFileError.ts @@ -0,0 +1,9 @@ +export class AnatomyDefinitionFileError extends Error { + constructor( + message: string, + public readonly path: string, + ) { + super(message); + this.name = "AnatomyDefinitionFileError"; + } +} diff --git a/apps/anatomy-cli/src/AnatomyFileTreeError.ts b/apps/anatomy-cli/src/AnatomyFileTreeError.ts new file mode 100644 index 0000000..911b33d --- /dev/null +++ b/apps/anatomy-cli/src/AnatomyFileTreeError.ts @@ -0,0 +1,9 @@ +export class AnatomyFileTreeError extends Error { + constructor( + message: string, + public readonly path: string, + ) { + super(message); + this.name = "AnatomyFileTreeError"; + } +} diff --git a/apps/anatomy-cli/src/AnatomyInstallError.ts b/apps/anatomy-cli/src/AnatomyInstallError.ts new file mode 100644 index 0000000..81efd4f --- /dev/null +++ b/apps/anatomy-cli/src/AnatomyInstallError.ts @@ -0,0 +1,6 @@ +export class AnatomyInstallError extends Error { + constructor(message: string, options?: ErrorOptions) { + super(message, options); + this.name = "AnatomyInstallError"; + } +} diff --git a/apps/anatomy-cli/src/DefaultAnatomyDefinitionFileName.ts b/apps/anatomy-cli/src/DefaultAnatomyDefinitionFileName.ts new file mode 100644 index 0000000..7a107b4 --- /dev/null +++ b/apps/anatomy-cli/src/DefaultAnatomyDefinitionFileName.ts @@ -0,0 +1 @@ +export const DefaultAnatomyDefinitionFileName = "anatomy.json"; diff --git a/apps/anatomy-cli/src/DefaultIgnoredNames.ts b/apps/anatomy-cli/src/DefaultIgnoredNames.ts new file mode 100644 index 0000000..aa50187 --- /dev/null +++ b/apps/anatomy-cli/src/DefaultIgnoredNames.ts @@ -0,0 +1,13 @@ +import { DefaultAnatomyDefinitionFileName } from "./DefaultAnatomyDefinitionFileName"; + +export const DefaultIgnoredNames = [ + ".git", + ".next", + ".output", + ".turbo", + "build", + "coverage", + "dist", + "node_modules", + DefaultAnatomyDefinitionFileName, +] as const; diff --git a/apps/anatomy-cli/src/agent-workflow.spec.ts b/apps/anatomy-cli/src/agent-workflow.spec.ts index fca95b7..7a70dc9 100644 --- a/apps/anatomy-cli/src/agent-workflow.spec.ts +++ b/apps/anatomy-cli/src/agent-workflow.spec.ts @@ -1,10 +1,12 @@ +import { AnatomyCheckWithDiagnosticsSchema, AnatomyQueryWithConstraintsSchema } from "@anatomy-cli/schemas"; import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; -import { resolve, join } from "node:path"; +import { join, resolve } from "node:path"; import { afterEach, beforeEach, describe, expect, it } from "vitest"; -import { AnatomyCheckWithDiagnosticsSchema, AnatomyQueryWithConstraintsSchema } from "@anatomy-cli/schemas"; -import { runAnatomyCli, type AnatomyCliDependencies } from "./cli"; -import { collectFileTree, findAnatomyDefinition, readAnatomyDefinition } from "./filesystem"; -import { formatAgentError } from "./format-agent-result"; +import { collectFileTree } from "./collectFileTree"; +import { findAnatomyDefinition } from "./findAnatomyDefinition"; +import { formatAgentError } from "./formatAgentError"; +import { readAnatomyDefinition } from "./readAnatomyDefinition"; +import { runAnatomyCli, type AnatomyCliDependencies } from "./runAnatomyCli"; const verificationRoot = resolve(import.meta.dirname, "../../../docs/verification/agent-workflow-tests"); let directory: string; diff --git a/apps/anatomy-cli/src/analyze-source-exports.spec.ts b/apps/anatomy-cli/src/analyze-source-exports.spec.ts index 2e22d9a..be80c8b 100644 --- a/apps/anatomy-cli/src/analyze-source-exports.spec.ts +++ b/apps/anatomy-cli/src/analyze-source-exports.spec.ts @@ -1,5 +1,5 @@ import { describe, expect, it } from "vitest"; -import { analyzeSourceExports } from "./analyze-source-exports"; +import { analyzeSourceExports } from "./analyzeSourceExports"; describe("JavaScript and TypeScript export analysis", () => { it.each([ diff --git a/apps/anatomy-cli/src/analyze-source-exports.ts b/apps/anatomy-cli/src/analyzeSourceExports.ts similarity index 100% rename from apps/anatomy-cli/src/analyze-source-exports.ts rename to apps/anatomy-cli/src/analyzeSourceExports.ts diff --git a/apps/anatomy-cli/src/cli-arguments.spec.ts b/apps/anatomy-cli/src/cli-arguments.spec.ts index 8d807a8..0e7f28e 100644 --- a/apps/anatomy-cli/src/cli-arguments.spec.ts +++ b/apps/anatomy-cli/src/cli-arguments.spec.ts @@ -1,5 +1,5 @@ import { describe, expect, it } from "vitest"; -import { parseCliArguments } from "./cli-arguments"; +import { parseCliArguments } from "./parseCliArguments"; describe("parseCliArguments", () => { it("supports query mode without reserving existing target directory names", () => { @@ -29,6 +29,7 @@ describe("parseCliArguments", () => { ignore: ["generated", "temp", "fixtures"], help: false, queryPath: null, + gitFiles: false, }); }); diff --git a/apps/anatomy-cli/src/cli.spec.ts b/apps/anatomy-cli/src/cli.spec.ts index d4e4f31..b11a886 100644 --- a/apps/anatomy-cli/src/cli.spec.ts +++ b/apps/anatomy-cli/src/cli.spec.ts @@ -1,8 +1,10 @@ -import { err, ok } from "neverthrow"; import { createEmptyAnatomyDraft } from "@anatomy-cli/anatomy/core"; +import { err, ok } from "neverthrow"; import { describe, expect, it, vi } from "vitest"; -import { AnatomyDefinitionFileError, AnatomyFileTreeError } from "./filesystem"; -import { AnatomyCliExitCode, runAnatomyCli, type AnatomyCliDependencies } from "./cli"; +import { AnatomyCliExitCode } from "./AnatomyCliExitCode"; +import { AnatomyDefinitionFileError } from "./AnatomyDefinitionFileError"; +import { AnatomyFileTreeError } from "./AnatomyFileTreeError"; +import { runAnatomyCli, type AnatomyCliDependencies } from "./runAnatomyCli"; const definition = createEmptyAnatomyDraft("Empty", "Allows an empty root"); diff --git a/apps/anatomy-cli/src/collectFileTree.ts b/apps/anatomy-cli/src/collectFileTree.ts new file mode 100644 index 0000000..c73fa13 --- /dev/null +++ b/apps/anatomy-cli/src/collectFileTree.ts @@ -0,0 +1,53 @@ +import type { AnatomyFileTreeEntry } from "@anatomy-cli/anatomy/core"; +import { err, ok, Result, ResultAsync } from "neverthrow"; +import { readdir } from "node:fs/promises"; +import { join, resolve } from "node:path"; +import { AnatomyFileTreeError } from "./AnatomyFileTreeError"; +import { DefaultIgnoredNames } from "./DefaultIgnoredNames"; + +const collectDirectory = async ( + directory: string, + ignoredNames: ReadonlySet, +): Promise> => { + const entriesResult = await ResultAsync.fromPromise( + readdir(directory, { withFileTypes: true }), + () => new AnatomyFileTreeError(`Unable to read target directory ${directory}`, directory), + ); + if (entriesResult.isErr()) return err(entriesResult.error); + + const tree: AnatomyFileTreeEntry[] = []; + const entries = [...entriesResult.value].sort((left, right) => + left.name.localeCompare(right.name), + ); + + for (const entry of entries) { + if (ignoredNames.has(entry.name) || entry.isSymbolicLink()) continue; + + if (entry.isDirectory()) { + const childPath = join(directory, entry.name); + const children = await collectDirectory(childPath, ignoredNames); + if (children.isErr()) return err(children.error); + tree.push({ + kind: "directory", + name: entry.name, + children: children.value, + }); + continue; + } + + if (entry.isFile()) { + tree.push({ kind: "file", name: entry.name }); + } + } + + return ok(tree); +}; + +export const collectFileTree = ( + targetPath: string, + additionalIgnoredNames: string[] = [], +): Promise> => { + const ignoredNames = new Set([...DefaultIgnoredNames, ...additionalIgnoredNames]); + + return collectDirectory(resolve(targetPath), ignoredNames); +}; diff --git a/apps/anatomy-cli/src/collectGitFileTree.ts b/apps/anatomy-cli/src/collectGitFileTree.ts new file mode 100644 index 0000000..218da70 --- /dev/null +++ b/apps/anatomy-cli/src/collectGitFileTree.ts @@ -0,0 +1,44 @@ +import type { AnatomyFileTreeEntry } from "@anatomy-cli/anatomy/core"; +import { err, ok, ResultAsync, type Result } from "neverthrow"; +import { execFile } from "node:child_process"; +import { lstat } from "node:fs/promises"; +import { resolve } from "node:path"; +import { promisify } from "node:util"; +import { AnatomyFileTreeError } from "./AnatomyFileTreeError"; + +export const collectGitFileTree = async ( + targetPath: string, +): Promise> => { + const directory = resolve(targetPath); + const inventory = await ResultAsync.fromPromise( + promisify(execFile)("git", ["-C", directory, "ls-files", "--cached", "--others", "--exclude-standard", "-z"], + { encoding: "utf8", maxBuffer: 16 * 1024 * 1024 }), + (cause) => new AnatomyFileTreeError(`Unable to list Git files in ${directory}: ${String(cause)}`, directory), + ); + if (inventory.isErr()) return err(inventory.error); + const tree: AnatomyFileTreeEntry[] = []; + for (const path of [...new Set(inventory.value.stdout.split("\0").filter(Boolean))].sort()) { + const absolutePath = resolve(directory, path); + const metadata = await ResultAsync.fromPromise(lstat(absolutePath), (cause) => cause); + if (metadata.isErr()) { + if ((metadata.error as NodeJS.ErrnoException).code === "ENOENT") continue; + return err(new AnatomyFileTreeError(`Unable to inspect ${absolutePath}: ${String(metadata.error)}`, absolutePath)); + } + if (!metadata.value.isFile()) { + return err(new AnatomyFileTreeError(`Git file checks require regular files; unsupported entry ${path}`, absolutePath)); + } + const parts = path.split("/"); + let siblings = tree; + for (const name of parts.slice(0, -1)) { + let entry = siblings.find((candidate) => candidate.name === name); + if (!entry) { + entry = { kind: "directory", name, children: [] }; + siblings.push(entry); + } + if (entry.kind !== "directory") return err(new AnatomyFileTreeError(`Conflicting Git path ${path}`, absolutePath)); + siblings = entry.children; + } + siblings.push({ kind: "file", name: parts.at(-1)! }); + } + return ok(tree); +}; diff --git a/apps/anatomy-cli/src/collect-source-exports.ts b/apps/anatomy-cli/src/collectSourceExports.ts similarity index 94% rename from apps/anatomy-cli/src/collect-source-exports.ts rename to apps/anatomy-cli/src/collectSourceExports.ts index 5aadce1..eb7b40d 100644 --- a/apps/anatomy-cli/src/collect-source-exports.ts +++ b/apps/anatomy-cli/src/collectSourceExports.ts @@ -3,7 +3,7 @@ import { resolve } from "node:path"; import { err, ok, ResultAsync, type Result } from "neverthrow"; import { AnatomySourceAnalysisError } from "@anatomy-cli/anatomy/core"; import type { AnatomyFunctionExportCheck, AnatomySourceExports } from "@anatomy-cli/schemas"; -import { analyzeSourceExports } from "./analyze-source-exports"; +import { analyzeSourceExports } from "./analyzeSourceExports"; export const collectSourceExports = async ( targetPath: string, diff --git a/apps/anatomy-cli/src/install-path.ts b/apps/anatomy-cli/src/configurePath.ts similarity index 54% rename from apps/anatomy-cli/src/install-path.ts rename to apps/anatomy-cli/src/configurePath.ts index e7a53d3..02acf7d 100644 --- a/apps/anatomy-cli/src/install-path.ts +++ b/apps/anatomy-cli/src/configurePath.ts @@ -1,34 +1,10 @@ -import { appendFileSync, constants, copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs"; -import { basename, dirname, join } from "node:path"; -import { spawnSync } from "node:child_process"; import { err, ok, Result } from "neverthrow"; -import { AnatomyInstallError } from "./install-options"; - -export const quoteShell = (value: string) => `'${value.replaceAll("'", "'\\''")}'`; - -export const getPathPlan = (bin: string, home: string, env: NodeJS.ProcessEnv) => { - const shell = basename(env.SHELL ?? "sh"); - if (shell === "fish") { - const config = env.XDG_CONFIG_HOME || join(home, ".config"); - const quoted = `'${bin.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'`; - return { profile: join(config, "fish", "config.fish"), line: `fish_add_path --prepend ${quoted}` }; - } - const line = `export PATH=${quoteShell(bin)}:"$PATH"`; - if (shell === "zsh") return { profile: join(env.ZDOTDIR || home, ".zshrc"), line }; - if (shell === "bash") { - const loginProfile = [".bash_profile", ".bash_login", ".profile"].map((file) => join(home, file)).find(existsSync); - return { profile: loginProfile ?? join(home, ".bashrc"), line }; - } - return { profile: shell === "sh" ? join(home, ".profile") : null, line }; -}; - -export const windowsPathScript = [ - '$ErrorActionPreference = "Stop"', - '$bin = $env:ANATOMY_INSTALL_BIN', - '$current = [Environment]::GetEnvironmentVariable("Path", "User")', - '$entries = @($current -split ";" | Where-Object { $_ -and $_.TrimEnd("\\") -ine $bin.TrimEnd("\\") })', - '[Environment]::SetEnvironmentVariable("Path", ((@($bin) + $entries) -join ";"), "User")', -].join("; "); +import { spawnSync } from "node:child_process"; +import { appendFileSync, constants, copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs"; +import { dirname } from "node:path"; +import { AnatomyInstallError } from "./AnatomyInstallError"; +import { getPathPlan } from "./getPathPlan"; +import { windowsPathScript } from "./windowsPathScript"; export const configurePath = ( bin: string, diff --git a/apps/anatomy-cli/src/filesystem.spec.ts b/apps/anatomy-cli/src/filesystem.spec.ts index 1401237..c7519dc 100644 --- a/apps/anatomy-cli/src/filesystem.spec.ts +++ b/apps/anatomy-cli/src/filesystem.spec.ts @@ -1,13 +1,11 @@ +import { createEmptyAnatomyDraft } from "@anatomy-cli/anatomy/core"; import { mkdir, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { afterEach, describe, expect, it } from "vitest"; -import { createEmptyAnatomyDraft } from "@anatomy-cli/anatomy/core"; -import { - collectFileTree, - findAnatomyDefinition, - readAnatomyDefinition, -} from "./filesystem"; +import { collectFileTree } from "./collectFileTree"; +import { findAnatomyDefinition } from "./findAnatomyDefinition"; +import { readAnatomyDefinition } from "./readAnatomyDefinition"; const testDirectory = join(process.cwd(), ".anatomy-cli-test"); const missingDefinitionDirectory = join( diff --git a/apps/anatomy-cli/src/filesystem.ts b/apps/anatomy-cli/src/filesystem.ts deleted file mode 100644 index 86d1d17..0000000 --- a/apps/anatomy-cli/src/filesystem.ts +++ /dev/null @@ -1,148 +0,0 @@ -import { access, readdir, readFile } from "node:fs/promises"; -import { dirname, join, resolve } from "node:path"; -import { Result, ResultAsync, err, ok } from "neverthrow"; -import { AnatomyDraftInputSchema, type AnatomyDraftInput } from "@anatomy-cli/schemas"; -import type { AnatomyFileTreeEntry } from "@anatomy-cli/anatomy/core"; - -export const DefaultAnatomyDefinitionFileName = "anatomy.json"; - -export const DefaultIgnoredNames = [ - ".git", - ".next", - ".output", - ".turbo", - "build", - "coverage", - "dist", - "node_modules", - DefaultAnatomyDefinitionFileName, -] as const; - -export class AnatomyDefinitionFileError extends Error { - constructor( - message: string, - public readonly path: string, - ) { - super(message); - this.name = "AnatomyDefinitionFileError"; - } -} - -export class AnatomyFileTreeError extends Error { - constructor( - message: string, - public readonly path: string, - ) { - super(message); - this.name = "AnatomyFileTreeError"; - } -} - -const parseJson = Result.fromThrowable( - JSON.parse, - () => new AnatomyDefinitionFileError("Definition is not valid JSON", ""), -); - -export const findAnatomyDefinition = async ( - targetPath: string, -): Promise> => { - const resolvedTargetPath = resolve(targetPath); - let directory = resolvedTargetPath; - - while (true) { - const candidatePath = join(directory, DefaultAnatomyDefinitionFileName); - const candidate = await ResultAsync.fromPromise( - access(candidatePath), - () => new AnatomyDefinitionFileError("Definition is not readable", candidatePath), - ); - if (candidate.isOk()) return ok(candidatePath); - - const parentDirectory = dirname(directory); - if (parentDirectory === directory) break; - directory = parentDirectory; - } - - return err( - new AnatomyDefinitionFileError( - `Unable to find ${DefaultAnatomyDefinitionFileName} from ${resolvedTargetPath} or its parent directories`, - resolvedTargetPath, - ), - ); -}; - -export const readAnatomyDefinition = ( - path: string, -): ResultAsync => { - const resolvedPath = resolve(path); - - return ResultAsync.fromPromise( - readFile(resolvedPath, "utf8"), - () => - new AnatomyDefinitionFileError( - `Unable to read Anatomy definition at ${resolvedPath}`, - resolvedPath, - ), - ).andThen((raw) => - parseJson(raw) - .mapErr((error) => new AnatomyDefinitionFileError(error.message, resolvedPath)) - .andThen((value) => { - const parsed = AnatomyDraftInputSchema.safeParse(value); - - return parsed.success - ? ok(parsed.data) - : err( - new AnatomyDefinitionFileError( - `Definition does not match the Anatomy schema: ${parsed.error.message}`, - resolvedPath, - ), - ); - }), - ); -}; - -const collectDirectory = async ( - directory: string, - ignoredNames: ReadonlySet, -): Promise> => { - const entriesResult = await ResultAsync.fromPromise( - readdir(directory, { withFileTypes: true }), - () => new AnatomyFileTreeError(`Unable to read target directory ${directory}`, directory), - ); - if (entriesResult.isErr()) return err(entriesResult.error); - - const tree: AnatomyFileTreeEntry[] = []; - const entries = [...entriesResult.value].sort((left, right) => - left.name.localeCompare(right.name), - ); - - for (const entry of entries) { - if (ignoredNames.has(entry.name) || entry.isSymbolicLink()) continue; - - if (entry.isDirectory()) { - const childPath = join(directory, entry.name); - const children = await collectDirectory(childPath, ignoredNames); - if (children.isErr()) return err(children.error); - tree.push({ - kind: "directory", - name: entry.name, - children: children.value, - }); - continue; - } - - if (entry.isFile()) { - tree.push({ kind: "file", name: entry.name }); - } - } - - return ok(tree); -}; - -export const collectFileTree = ( - targetPath: string, - additionalIgnoredNames: string[] = [], -): Promise> => { - const ignoredNames = new Set([...DefaultIgnoredNames, ...additionalIgnoredNames]); - - return collectDirectory(resolve(targetPath), ignoredNames); -}; diff --git a/apps/anatomy-cli/src/findAnatomyDefinition.ts b/apps/anatomy-cli/src/findAnatomyDefinition.ts new file mode 100644 index 0000000..a556e61 --- /dev/null +++ b/apps/anatomy-cli/src/findAnatomyDefinition.ts @@ -0,0 +1,32 @@ +import { err, ok, Result, ResultAsync } from "neverthrow"; +import { access } from "node:fs/promises"; +import { dirname, join, resolve } from "node:path"; +import { AnatomyDefinitionFileError } from "./AnatomyDefinitionFileError"; +import { DefaultAnatomyDefinitionFileName } from "./DefaultAnatomyDefinitionFileName"; + +export const findAnatomyDefinition = async ( + targetPath: string, +): Promise> => { + const resolvedTargetPath = resolve(targetPath); + let directory = resolvedTargetPath; + + while (true) { + const candidatePath = join(directory, DefaultAnatomyDefinitionFileName); + const candidate = await ResultAsync.fromPromise( + access(candidatePath), + () => new AnatomyDefinitionFileError("Definition is not readable", candidatePath), + ); + if (candidate.isOk()) return ok(candidatePath); + + const parentDirectory = dirname(directory); + if (parentDirectory === directory) break; + directory = parentDirectory; + } + + return err( + new AnatomyDefinitionFileError( + `Unable to find ${DefaultAnatomyDefinitionFileName} from ${resolvedTargetPath} or its parent directories`, + resolvedTargetPath, + ), + ); +}; diff --git a/apps/anatomy-cli/src/format-agent-result.spec.ts b/apps/anatomy-cli/src/format-agent-result.spec.ts index 3752bfc..a4c5e0c 100644 --- a/apps/anatomy-cli/src/format-agent-result.spec.ts +++ b/apps/anatomy-cli/src/format-agent-result.spec.ts @@ -1,7 +1,7 @@ -import { describe, expect, it } from "vitest"; -import { AnatomyDraftInputSchema } from "@anatomy-cli/schemas"; import { queryAnatomy } from "@anatomy-cli/anatomy/core"; -import { formatAgentQuery } from "./format-agent-result"; +import { AnatomyDraftInputSchema } from "@anatomy-cli/schemas"; +import { describe, expect, it } from "vitest"; +import { formatAgentQuery } from "./formatAgentQuery"; const definition = AnatomyDraftInputSchema.parse({ name: "Readable query", purpose: "Show constraints before editing", diff --git a/apps/anatomy-cli/src/formatAgentCheck.ts b/apps/anatomy-cli/src/formatAgentCheck.ts new file mode 100644 index 0000000..41c458d --- /dev/null +++ b/apps/anatomy-cli/src/formatAgentCheck.ts @@ -0,0 +1,44 @@ +import { AnatomyCheckCode, anatomyRulePaths, type AnatomyCheckResult, type AnatomyFileTreeEntry } from "@anatomy-cli/anatomy/core"; +import type { AnatomyCheckWithDiagnostics, AnatomyDraftInput } from "@anatomy-cli/schemas"; +import { resolve } from "node:path"; +import { DefaultIgnoredNames } from "./DefaultIgnoredNames"; + +export const formatAgentCheck = ( + result: AnatomyCheckResult, + definition: AnatomyDraftInput, + definitionPath: string, + targetPath: string, + tree: AnatomyFileTreeEntry[], + ignore: string[], + gitFiles = false, +): string => { + const rules = anatomyRulePaths(definition); + const actualByPath = new Map([[".", tree]]); + const visit = (entries: AnatomyFileTreeEntry[], parent: string): void => { + for (const entry of entries) { + const path = parent ? `${parent}/${entry.name}` : entry.name; + actualByPath.set(path, [entry]); + if (entry.kind === "directory") visit(entry.children, path); + } + }; + visit(tree, ""); + const report: AnatomyCheckWithDiagnostics = { + ...result, contractVersion: 1, operation: "check", + definition: { path: resolve(definitionPath), name: definition.name, schemaVersion: definition.structure.schemaVersion }, + targetPath: resolve(targetPath), + fileSelection: gitFiles ? "git" : "filesystem", + ignoredNames: gitFiles ? [] : [...new Set([...DefaultIgnoredNames, ...ignore])], + issues: result.issues.map((issue) => { + const rule = issue.constraintId ? rules.get(issue.constraintId) : undefined; + const entries = actualByPath.get(issue.path) ?? []; + const actual = issue.code === AnatomyCheckCode.missingRequired || issue.code === AnatomyCheckCode.oneOfMismatch + ? issue.path === "." ? tree : entries.flatMap((entry) => entry.kind === "directory" ? entry.children : []) + : entries; + return { + ...issue, rulePath: rule?.rulePath ?? null, expected: rule?.node ?? null, + actual: actual.map(({ kind, name }) => ({ kind, name })), + }; + }), + }; + return JSON.stringify(report, null, 2); +}; diff --git a/apps/anatomy-cli/src/formatAgentError.ts b/apps/anatomy-cli/src/formatAgentError.ts new file mode 100644 index 0000000..b1abb2a --- /dev/null +++ b/apps/anatomy-cli/src/formatAgentError.ts @@ -0,0 +1,4 @@ +export const formatAgentError = (error: Error): string => JSON.stringify({ + contractVersion: 1, operation: "error", + error: { code: error.name, message: error.message, ...("path" in error ? { path: error.path } : {}) }, +}, null, 2); diff --git a/apps/anatomy-cli/src/format-agent-result.ts b/apps/anatomy-cli/src/formatAgentQuery.ts similarity index 62% rename from apps/anatomy-cli/src/format-agent-result.ts rename to apps/anatomy-cli/src/formatAgentQuery.ts index 1326e76..69885c0 100644 --- a/apps/anatomy-cli/src/format-agent-result.ts +++ b/apps/anatomy-cli/src/formatAgentQuery.ts @@ -1,44 +1,6 @@ +import { resolveAnatomyExportName } from "@anatomy-cli/anatomy/core"; +import type { AnatomyDraftInput, AnatomyNode, AnatomyPolicies, AnatomyQuantity, AnatomyQueryWithConstraints } from "@anatomy-cli/schemas"; import { resolve } from "node:path"; -import { AnatomyCheckCode, anatomyRulePaths, resolveAnatomyExportName, type AnatomyCheckResult, type AnatomyFileTreeEntry } from "@anatomy-cli/anatomy/core"; -import type { AnatomyCheckWithDiagnostics, AnatomyDraftInput, AnatomyNode, AnatomyPolicies, AnatomyQueryWithConstraints, AnatomyQuantity } from "@anatomy-cli/schemas"; -import { DefaultIgnoredNames } from "./filesystem"; - -export const formatAgentCheck = ( - result: AnatomyCheckResult, - definition: AnatomyDraftInput, - definitionPath: string, - targetPath: string, - tree: AnatomyFileTreeEntry[], - ignore: string[], -): string => { - const rules = anatomyRulePaths(definition); - const actualByPath = new Map([[".", tree]]); - const visit = (entries: AnatomyFileTreeEntry[], parent: string): void => { - for (const entry of entries) { - const path = parent ? `${parent}/${entry.name}` : entry.name; - actualByPath.set(path, [entry]); - if (entry.kind === "directory") visit(entry.children, path); - } - }; - visit(tree, ""); - const report: AnatomyCheckWithDiagnostics = { - ...result, contractVersion: 1, operation: "check", - definition: { path: resolve(definitionPath), name: definition.name, schemaVersion: definition.structure.schemaVersion }, - targetPath: resolve(targetPath), ignoredNames: [...new Set([...DefaultIgnoredNames, ...ignore])], - issues: result.issues.map((issue) => { - const rule = issue.constraintId ? rules.get(issue.constraintId) : undefined; - const entries = actualByPath.get(issue.path) ?? []; - const actual = issue.code === AnatomyCheckCode.missingRequired || issue.code === AnatomyCheckCode.oneOfMismatch - ? issue.path === "." ? tree : entries.flatMap((entry) => entry.kind === "directory" ? entry.children : []) - : entries; - return { - ...issue, rulePath: rule?.rulePath ?? null, expected: rule?.node ?? null, - actual: actual.map(({ kind, name }) => ({ kind, name })), - }; - }), - }; - return JSON.stringify(report, null, 2); -}; export const formatAgentQuery = ( result: AnatomyQueryWithConstraints, @@ -114,8 +76,3 @@ export const formatAgentQuery = ( "Query only. Run anatomy with the same target and definition, without --query, to check actual files.", ].filter(Boolean).join("\n"); }; - -export const formatAgentError = (error: Error): string => JSON.stringify({ - contractVersion: 1, operation: "error", - error: { code: error.name, message: error.message, ...("path" in error ? { path: error.path } : {}) }, -}, null, 2); diff --git a/apps/anatomy-cli/src/format-result.ts b/apps/anatomy-cli/src/formatHumanResult.ts similarity index 82% rename from apps/anatomy-cli/src/format-result.ts rename to apps/anatomy-cli/src/formatHumanResult.ts index 81735dc..0fadb41 100644 --- a/apps/anatomy-cli/src/format-result.ts +++ b/apps/anatomy-cli/src/formatHumanResult.ts @@ -13,7 +13,3 @@ export const formatHumanResult = (result: AnatomyCheckResult): string => { ), ].join("\n"); }; - -export const formatJsonResult = (result: AnatomyCheckResult): string => { - return JSON.stringify(result, null, 2); -}; diff --git a/apps/anatomy-cli/src/formatJsonResult.ts b/apps/anatomy-cli/src/formatJsonResult.ts new file mode 100644 index 0000000..1b92da8 --- /dev/null +++ b/apps/anatomy-cli/src/formatJsonResult.ts @@ -0,0 +1,5 @@ +import type { AnatomyCheckResult } from "@anatomy-cli/anatomy/core"; + +export const formatJsonResult = (result: AnatomyCheckResult): string => { + return JSON.stringify(result, null, 2); +}; diff --git a/apps/anatomy-cli/src/function-export-workflow.spec.ts b/apps/anatomy-cli/src/function-export-workflow.spec.ts index c3a5a1f..c331a48 100644 --- a/apps/anatomy-cli/src/function-export-workflow.spec.ts +++ b/apps/anatomy-cli/src/function-export-workflow.spec.ts @@ -1,10 +1,12 @@ +import { AnatomyCheckWithDiagnosticsSchema } from "@anatomy-cli/schemas"; import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; import { join, resolve } from "node:path"; import { afterEach, beforeEach, describe, expect, it } from "vitest"; -import { AnatomyCheckWithDiagnosticsSchema } from "@anatomy-cli/schemas"; -import { runAnatomyCli } from "./cli"; -import { collectFileTree, findAnatomyDefinition, readAnatomyDefinition } from "./filesystem"; -import { collectSourceExports } from "./collect-source-exports"; +import { collectSourceExports } from "./collectSourceExports"; +import { collectFileTree } from "./collectFileTree"; +import { findAnatomyDefinition } from "./findAnatomyDefinition"; +import { readAnatomyDefinition } from "./readAnatomyDefinition"; +import { runAnatomyCli } from "./runAnatomyCli"; const verificationRoot = resolve(import.meta.dirname, "../../../docs/verification/function-export-tests"); let directory: string; diff --git a/apps/anatomy-cli/src/getPathPlan.ts b/apps/anatomy-cli/src/getPathPlan.ts new file mode 100644 index 0000000..785eff9 --- /dev/null +++ b/apps/anatomy-cli/src/getPathPlan.ts @@ -0,0 +1,19 @@ +import { existsSync } from "node:fs"; +import { basename, join } from "node:path"; +import { quoteShell } from "./quoteShell"; + +export const getPathPlan = (bin: string, home: string, env: NodeJS.ProcessEnv) => { + const shell = basename(env.SHELL ?? "sh"); + if (shell === "fish") { + const config = env.XDG_CONFIG_HOME || join(home, ".config"); + const quoted = `'${bin.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'`; + return { profile: join(config, "fish", "config.fish"), line: `fish_add_path --prepend ${quoted}` }; + } + const line = `export PATH=${quoteShell(bin)}:"$PATH"`; + if (shell === "zsh") return { profile: join(env.ZDOTDIR || home, ".zshrc"), line }; + if (shell === "bash") { + const loginProfile = [".bash_profile", ".bash_login", ".profile"].map((file) => join(home, file)).find(existsSync); + return { profile: loginProfile ?? join(home, ".bashrc"), line }; + } + return { profile: shell === "sh" ? join(home, ".profile") : null, line }; +}; diff --git a/apps/anatomy-cli/src/git-files.spec.ts b/apps/anatomy-cli/src/git-files.spec.ts new file mode 100644 index 0000000..726bcb6 --- /dev/null +++ b/apps/anatomy-cli/src/git-files.spec.ts @@ -0,0 +1,84 @@ +import { execFileSync } from "node:child_process"; +import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises"; +import { resolve } from "node:path"; +import { afterEach, describe, expect, it, vi } from "vitest"; +import { collectGitFileTree } from "./collectGitFileTree"; +import { parseCliArguments } from "./parseCliArguments"; +import { runAnatomyCli } from "./runAnatomyCli"; + +const temporaryDirectories: string[] = []; +const fixture = async () => { + const base = resolve(import.meta.dirname, "../../../docs/verification"); + await mkdir(base, { recursive: true }); + const directory = await mkdtemp(`${base}/git-files-`); + temporaryDirectories.push(directory); + execFileSync("git", ["init", "--quiet", directory]); + await writeFile(resolve(directory, ".gitignore"), "local/\nnode_modules/\n"); + await mkdir(resolve(directory, "local")); + await writeFile(resolve(directory, "local/tracked.ts"), "export const tracked = () => 1;"); + execFileSync("git", ["-C", directory, "add", "-f", "local/tracked.ts"]); + await writeFile(resolve(directory, "local/private.ts"), "local only"); + return directory; +}; + +afterEach(async () => { + vi.restoreAllMocks(); + vi.unstubAllEnvs(); + await Promise.all(temporaryDirectories.splice(0).map((path) => rm(path, { recursive: true, force: true }))); +}); + +describe("Git file selection", () => { + it("includes ignored tracked files and untracked files, but excludes local ignored files", async () => { + const directory = await fixture(); + await writeFile(resolve(directory, "new\nfile.ts"), "export const newFile = () => 1;"); + expect((await collectGitFileTree(directory))._unsafeUnwrap()).toEqual([ + { kind: "file", name: ".gitignore" }, + { kind: "directory", name: "local", children: [{ kind: "file", name: "tracked.ts" }] }, + { kind: "file", name: "new\nfile.ts" }, + ]); + }); + + it("reads the working tree rather than treating deleted index entries as existing files", async () => { + const directory = await fixture(); + await rm(resolve(directory, "local/tracked.ts")); + expect((await collectGitFileTree(directory))._unsafeUnwrap()).toEqual([{ kind: "file", name: ".gitignore" }]); + }); + + it("limits selection to the requested subtree", async () => { + const directory = await fixture(); + expect((await collectGitFileTree(resolve(directory, "local")))._unsafeUnwrap()) + .toEqual([{ kind: "file", name: "tracked.ts" }]); + }); + + it("fails closed on symlinks and directories outside a Git repository", async () => { + const directory = await fixture(); + await symlink("local/tracked.ts", resolve(directory, "linked.ts")); + expect((await collectGitFileTree(directory))._unsafeUnwrapErr().message).toContain("unsupported entry linked.ts"); + await rm(resolve(directory, ".git"), { recursive: true }); + vi.stubEnv("GIT_CEILING_DIRECTORIES", resolve(directory, "..")); + const result = await collectGitFileTree(directory); + expect(result.isErr()).toBe(true); + }); + + it("blocks a new undeclared file through the CLI and reports Git selection accurately", async () => { + const output = vi.spyOn(process.stdout, "write").mockReturnValue(true); + const directory = await fixture(); + const definitionPath = resolve(directory, "local/contract.json"); + await writeFile(definitionPath, JSON.stringify({ name: "Git fixture", purpose: "No source files allowed", structure: { + schemaVersion: 1, + defaultPolicies: { missingRequired: "block", unexpectedEntry: "block", nameMismatch: "block", nestingMismatch: "block" }, + root: { children: [{ kind: "file", name: { type: "literal", value: ".gitignore" }, quantity: "exactly_one" }] }, + } })); + await rm(resolve(directory, "local/tracked.ts")); + expect((await runAnatomyCli([directory, "--git-files", "--definition", definitionPath]))._unsafeUnwrap()).toBe(0); + await writeFile(resolve(directory, "extra.ts"), "export const extra = () => 1;"); + expect((await runAnatomyCli([directory, "--git-files", "--definition", definitionPath, "--format", "json"]))._unsafeUnwrap()).toBe(1); + const report = JSON.parse(String(output.mock.calls.at(-1)![0])); + expect(report).toMatchObject({ fileSelection: "git", ignoredNames: [], conforms: false }); + }); + + it("does not permit ignores to hide files in Git mode", () => { + expect(parseCliArguments(["--git-files"])._unsafeUnwrap().gitFiles).toBe(true); + expect(parseCliArguments(["--git-files", "--ignore", "src"]).isErr()).toBe(true); + }); +}); diff --git a/apps/anatomy-cli/src/index.ts b/apps/anatomy-cli/src/index.ts index 2189b27..cdef334 100644 --- a/apps/anatomy-cli/src/index.ts +++ b/apps/anatomy-cli/src/index.ts @@ -1,7 +1,21 @@ -export * from "./cli"; -export * from "./cli-arguments"; -export * from "./filesystem"; -export * from "./format-result"; -export * from "./format-agent-result"; -export * from "./analyze-source-exports"; -export * from "./collect-source-exports"; +export * from "./analyzeSourceExports"; +export * from "./AnatomyCliArgumentError"; +export * from "./AnatomyCliExitCode"; +export * from "./AnatomyCliFormatValues"; +export * from "./AnatomyCliUsage"; +export * from "./AnatomyDefinitionFileError"; +export * from "./AnatomyFileTreeError"; +export * from "./collectSourceExports"; +export * from "./collectFileTree"; +export * from "./collectGitFileTree"; +export * from "./DefaultAnatomyDefinitionFileName"; +export * from "./DefaultIgnoredNames"; +export * from "./findAnatomyDefinition"; +export * from "./formatAgentCheck"; +export * from "./formatAgentError"; +export * from "./formatAgentQuery"; +export * from "./formatHumanResult"; +export * from "./formatJsonResult"; +export * from "./parseCliArguments"; +export * from "./readAnatomyDefinition"; +export * from "./runAnatomyCli"; diff --git a/apps/anatomy-cli/src/install-main.ts b/apps/anatomy-cli/src/install-main.ts index 4d54e90..65714e1 100644 --- a/apps/anatomy-cli/src/install-main.ts +++ b/apps/anatomy-cli/src/install-main.ts @@ -1,11 +1,12 @@ #!/usr/bin/env node +import { ok } from "neverthrow"; +import { homedir } from "node:os"; import { dirname, resolve } from "node:path"; import { fileURLToPath } from "node:url"; -import { homedir } from "node:os"; -import { ok } from "neverthrow"; -import { installUsage, parseInstallOptions } from "./install-options"; -import { runInstallation } from "./install"; +import { installUsage } from "./installUsage"; +import { parseInstallOptions } from "./parseInstallOptions"; +import { runInstallation } from "./runInstallation"; const result = parseInstallOptions(process.argv.slice(2)).andThen((options) => options.help ? ok([installUsage]) : runInstallation(options, { diff --git a/apps/anatomy-cli/src/install.spec.ts b/apps/anatomy-cli/src/install.spec.ts index 442948e..1b66fca 100644 --- a/apps/anatomy-cli/src/install.spec.ts +++ b/apps/anatomy-cli/src/install.spec.ts @@ -2,9 +2,12 @@ import { execFileSync } from "node:child_process"; import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs"; import { join, resolve } from "node:path"; import { afterEach, beforeEach, describe, expect, it } from "vitest"; -import { parseInstallOptions, type InstallOptions } from "./install-options"; -import { getPathPlan, quoteShell, windowsPathScript } from "./install-path"; -import { runInstallation, windowsLauncher, type InstallContext } from "./install"; +import { getPathPlan } from "./getPathPlan"; +import { parseInstallOptions, type InstallOptions } from "./parseInstallOptions"; +import { quoteShell } from "./quoteShell"; +import { runInstallation, type InstallContext } from "./runInstallation"; +import { windowsLauncher } from "./windowsLauncher"; +import { windowsPathScript } from "./windowsPathScript"; const projectRoot = resolve(import.meta.dirname, "../../.."); let temporary: string; diff --git a/apps/anatomy-cli/src/installUsage.ts b/apps/anatomy-cli/src/installUsage.ts new file mode 100644 index 0000000..2bc6bbb --- /dev/null +++ b/apps/anatomy-cli/src/installUsage.ts @@ -0,0 +1,19 @@ +export const installUsage = `Install Anatomy once, then run: anatomy ./src + + npm: npx anatomy-cli + pnpm: pnpm dlx anatomy-cli + Bun: bunx anatomy-cli + +Requires Node.js 18+. No administrator privileges or project changes. +Downloads are handled by your package manager; the installer copies this release. + +Options: + --prefix Install directory (default: ~/.anatomy) + --no-modify-path Leave shell profiles and user PATH unchanged + --uninstall Remove the managed CLI from the install directory + --install Explicitly select the installer + -h, --help Show this help without changing anything + +Rerun the installer with anatomy-cli@latest to upgrade. +For a one-off check instead: anatomy-cli ./src +`; diff --git a/apps/anatomy-cli/src/main.ts b/apps/anatomy-cli/src/main.ts index 4595998..fe01cb0 100755 --- a/apps/anatomy-cli/src/main.ts +++ b/apps/anatomy-cli/src/main.ts @@ -1,8 +1,9 @@ #!/usr/bin/env node -import { AnatomyCliExitCode, runAnatomyCli } from "./cli"; -import { AnatomyCliUsage } from "./cli-arguments"; -import { formatAgentError } from "./format-agent-result"; +import { AnatomyCliExitCode } from "./AnatomyCliExitCode"; +import { AnatomyCliUsage } from "./AnatomyCliUsage"; +import { formatAgentError } from "./formatAgentError"; +import { runAnatomyCli } from "./runAnatomyCli"; const result = await runAnatomyCli(process.argv.slice(2)); diff --git a/apps/anatomy-cli/src/cli-arguments.ts b/apps/anatomy-cli/src/parseCliArguments.ts similarity index 80% rename from apps/anatomy-cli/src/cli-arguments.ts rename to apps/anatomy-cli/src/parseCliArguments.ts index d062940..8977d4a 100644 --- a/apps/anatomy-cli/src/cli-arguments.ts +++ b/apps/anatomy-cli/src/parseCliArguments.ts @@ -1,6 +1,6 @@ import { err, ok, type Result } from "neverthrow"; - -export const AnatomyCliFormatValues = ["human", "json"] as const; +import { AnatomyCliArgumentError } from "./AnatomyCliArgumentError"; +import { AnatomyCliFormatValues } from "./AnatomyCliFormatValues"; export type AnatomyCliOptions = { definitionPath: string | null; @@ -9,15 +9,9 @@ export type AnatomyCliOptions = { ignore: string[]; help: boolean; queryPath: string | null; + gitFiles: boolean; }; -export class AnatomyCliArgumentError extends Error { - constructor(message: string) { - super(message); - this.name = "AnatomyCliArgumentError"; - } -} - const getOptionValue = ( args: string[], index: number, @@ -40,6 +34,7 @@ export const parseCliArguments = ( ignore: [], help: false, queryPath: null, + gitFiles: false, }; const consumedIndexes = new Set(); let targetSpecified = false; @@ -53,6 +48,11 @@ export const parseCliArguments = ( continue; } + if (argument === "--git-files") { + options.gitFiles = true; + continue; + } + if (argument === "--definition" || argument === "-d") { const value = getOptionValue(args, index, argument); if (value.isErr()) return err(value.error); @@ -122,20 +122,8 @@ export const parseCliArguments = ( if (options.queryPath !== null && options.ignore.length > 0) { return err(new AnatomyCliArgumentError("--ignore is only supported for checks; queries describe declared constraints")); } + if (options.gitFiles && options.ignore.length > 0) { + return err(new AnatomyCliArgumentError("--git-files cannot be combined with --ignore")); + } return ok(options); }; - -export const AnatomyCliUsage = [ - "Usage: anatomy [target] [options]", - "", - "Arguments:", - " target Directory to check (default: current directory)", - "", - "Options:", - " -d, --definition Anatomy JSON (default: nearest anatomy.json)", - " -t, --target Alternate form of the target argument", - " --format human or json (default: human)", - " --query Query constraints relative to target (path may not exist)", - " --ignore Comma-separated names; may be repeated", - " -h, --help Show this help", -].join("\n"); diff --git a/apps/anatomy-cli/src/install-options.ts b/apps/anatomy-cli/src/parseInstallOptions.ts similarity index 65% rename from apps/anatomy-cli/src/install-options.ts rename to apps/anatomy-cli/src/parseInstallOptions.ts index 4ae14ad..9e9cc42 100644 --- a/apps/anatomy-cli/src/install-options.ts +++ b/apps/anatomy-cli/src/parseInstallOptions.ts @@ -1,13 +1,7 @@ +import { err, ok, type Result } from "neverthrow"; import { homedir } from "node:os"; import { isAbsolute, join, parse, resolve } from "node:path"; -import { err, ok, type Result } from "neverthrow"; - -export class AnatomyInstallError extends Error { - constructor(message: string, options?: ErrorOptions) { - super(message, options); - this.name = "AnatomyInstallError"; - } -} +import { AnatomyInstallError } from "./AnatomyInstallError"; export type InstallOptions = { prefix: string; @@ -16,26 +10,6 @@ export type InstallOptions = { help: boolean; }; -export const installUsage = `Install Anatomy once, then run: anatomy ./src - - npm: npx anatomy-cli - pnpm: pnpm dlx anatomy-cli - Bun: bunx anatomy-cli - -Requires Node.js 18+. No administrator privileges or project changes. -Downloads are handled by your package manager; the installer copies this release. - -Options: - --prefix Install directory (default: ~/.anatomy) - --no-modify-path Leave shell profiles and user PATH unchanged - --uninstall Remove the managed CLI from the install directory - --install Explicitly select the installer - -h, --help Show this help without changing anything - -Rerun the installer with anatomy-cli@latest to upgrade. -For a one-off check instead: anatomy-cli ./src -`; - export const parseInstallOptions = ( args: string[], home = homedir(), diff --git a/apps/anatomy-cli/src/posixLauncher.ts b/apps/anatomy-cli/src/posixLauncher.ts new file mode 100644 index 0000000..2508e60 --- /dev/null +++ b/apps/anatomy-cli/src/posixLauncher.ts @@ -0,0 +1 @@ +export const posixLauncher = '#!/bin/sh\nexec node "$(dirname "$0")/../anatomy.mjs" "$@"\n'; diff --git a/apps/anatomy-cli/src/quoteShell.ts b/apps/anatomy-cli/src/quoteShell.ts new file mode 100644 index 0000000..4b5b524 --- /dev/null +++ b/apps/anatomy-cli/src/quoteShell.ts @@ -0,0 +1 @@ +export const quoteShell = (value: string) => `'${value.replaceAll("'", "'\\''")}'`; diff --git a/apps/anatomy-cli/src/readAnatomyDefinition.ts b/apps/anatomy-cli/src/readAnatomyDefinition.ts new file mode 100644 index 0000000..9237a53 --- /dev/null +++ b/apps/anatomy-cli/src/readAnatomyDefinition.ts @@ -0,0 +1,40 @@ +import { AnatomyDraftInputSchema, type AnatomyDraftInput } from "@anatomy-cli/schemas"; +import { err, ok, Result, ResultAsync } from "neverthrow"; +import { readFile } from "node:fs/promises"; +import { resolve } from "node:path"; +import { AnatomyDefinitionFileError } from "./AnatomyDefinitionFileError"; + +const parseJson = Result.fromThrowable( + JSON.parse, + () => new AnatomyDefinitionFileError("Definition is not valid JSON", ""), +); + +export const readAnatomyDefinition = ( + path: string, +): ResultAsync => { + const resolvedPath = resolve(path); + + return ResultAsync.fromPromise( + readFile(resolvedPath, "utf8"), + () => + new AnatomyDefinitionFileError( + `Unable to read Anatomy definition at ${resolvedPath}`, + resolvedPath, + ), + ).andThen((raw) => + parseJson(raw) + .mapErr((error) => new AnatomyDefinitionFileError(error.message, resolvedPath)) + .andThen((value) => { + const parsed = AnatomyDraftInputSchema.safeParse(value); + + return parsed.success + ? ok(parsed.data) + : err( + new AnatomyDefinitionFileError( + `Definition does not match the Anatomy schema: ${parsed.error.message}`, + resolvedPath, + ), + ); + }), + ); +}; diff --git a/apps/anatomy-cli/src/repository-contract.spec.ts b/apps/anatomy-cli/src/repository-contract.spec.ts new file mode 100644 index 0000000..cbf3b17 --- /dev/null +++ b/apps/anatomy-cli/src/repository-contract.spec.ts @@ -0,0 +1,156 @@ +import { readFile } from "node:fs/promises"; +import { basename, dirname, resolve } from "node:path"; +import ts from "typescript"; +import { describe, expect, it } from "vitest"; +import { anatomyRulePaths, checkAnatomy, planAnatomyCheck, type AnatomyFileTreeEntry } from "@anatomy-cli/anatomy/core"; +import { collectGitFileTree } from "./collectGitFileTree"; +import { collectSourceExports } from "./collectSourceExports"; +import { readAnatomyDefinition } from "./readAnatomyDefinition"; + +const root = resolve(import.meta.dirname, "../../.."); +const load = async () => { + const definition = (await readAnatomyDefinition(resolve(root, "anatomy.json")))._unsafeUnwrap(); + const entries = (await collectGitFileTree(root))._unsafeUnwrap(); + const plan = planAnatomyCheck(definition, entries)._unsafeUnwrap(); + const exports = (await collectSourceExports(root, plan.exportChecks))._unsafeUnwrap(); + return { definition, entries, exports, plan }; +}; + +const removeFile = (entries: AnatomyFileTreeEntry[], path: string): AnatomyFileTreeEntry[] => { + const [name, ...rest] = path.split("/"); + return entries.flatMap((entry) => entry.name !== name ? [entry] + : rest.length === 0 ? [] + : entry.kind === "directory" ? [{ ...entry, children: removeFile(entry.children, rest.join("/")) }] : [entry]); +}; + +describe("whole repository Anatomy contract", () => { + it("covers every Git-visible project file with a strict explicit rule", async () => { + const { definition, entries, exports } = await load(); + expect(checkAnatomy(definition, entries, exports)._unsafeUnwrap().issues).toEqual([]); + expect(definition.structure.defaultPolicies).toEqual({ missingRequired: "block", unexpectedEntry: "block", nameMismatch: "block", nestingMismatch: "block" }); + for (const { node } of anatomyRulePaths(definition).values()) { + expect(node.kind).not.toBe("one_of"); + if (node.kind === "one_of") continue; + expect(node.name.type).toBe("literal"); + expect(node.quantity).toBe("exactly_one"); + expect(node.policyOverrides).toEqual({}); + if (node.kind === "file" && node.exports) expect(node.exports.policy).toBe("block"); + } + }); + + it("blocks additions and missing files in every workspace and in repository infrastructure", async () => { + const { definition, entries, exports } = await load(); + for (const path of ["package.json", ".github/workflows/ci.yml", "apps/anatomy-cli/src/runAnatomyCli.ts", + "apps/docs/src/pages/HomePage.tsx", "packages/anatomy/src/core/checkAnatomy.ts", + "packages/schemas/src/anatomy/AnatomyDraftInputSchema.ts", "packages/anatomy-cli-config/src/anatomies/service.anatomy.json"]) { + const result = checkAnatomy(definition, removeFile(entries, path), exports)._unsafeUnwrap(); + expect(result.conforms, path).toBe(false); + expect(result.issues.some((issue) => issue.code === "missing_required" && issue.path === dirname(path) && issue.message.includes(basename(path))), path).toBe(true); + } + const addAtEveryDirectory = (tree: AnatomyFileTreeEntry[]): AnatomyFileTreeEntry[] => [ + ...tree.map((entry) => entry.kind === "directory" ? { ...entry, children: addAtEveryDirectory(entry.children) } : entry), + { kind: "file", name: "undeclared.ts" }, + ]; + const result = checkAnatomy(definition, addAtEveryDirectory(entries), exports)._unsafeUnwrap(); + const directories = [...anatomyRulePaths(definition).values()].filter(({ node }) => node.kind === "directory"); + expect(result.issues.filter((issue) => issue.code === "unexpected_entry")).toHaveLength(directories.length + 1); + }); + + it("blocks wrong function names and additional runtime exports for every selected source file", async () => { + const { definition, entries, exports, plan } = await load(); + expect(plan.exportChecks.length).toBeGreaterThan(90); + for (const check of plan.exportChecks) { + const changed = new Map(exports); + changed.set(check.path, [{ name: "wrongExportName", kind: "function" }]); + const result = checkAnatomy(definition, entries, changed)._unsafeUnwrap(); + expect(result.issues.some((issue) => issue.path === check.path && issue.code === "export_name_mismatch"), check.path).toBe(true); + changed.set(check.path, [...exports.get(check.path)!, { name: "extra", kind: "value" }]); + expect(checkAnatomy(definition, entries, changed)._unsafeUnwrap().conforms, check.path).toBe(false); + } + }); + + it("requires a reviewed role for every source file without a function rule", async () => { + const { definition } = await load(); + const coverage = JSON.parse(await readFile(resolve(root, "anatomy.coverage.json"), "utf8")) as { + exceptions: Record; + }; + const used = new Set(); + const visit = async (nodes: typeof definition.structure.root.children, parent = "") => { + for (const node of nodes) { + if (node.kind === "one_of") continue; + const path = parent ? `${parent}/${node.name.value}` : node.name.value; + if (node.kind === "directory") { await visit(node.children, path); continue; } + if (!/\.[cm]?[jt]sx?$/.test(path)) continue; + if (node.exports) { expect(coverage.exceptions[path], path).toBeUndefined(); continue; } + const exception = coverage.exceptions[path]; + expect(exception, `${path} has neither a function contract nor a reviewed role`).toBeDefined(); + if (!exception) continue; + used.add(path); + expect(exception.reason.length, path).toBeGreaterThan(15); + const source = ts.createSourceFile(path, await readFile(resolve(root, path), "utf8"), ts.ScriptTarget.Latest, true); + const hasExport = (node: ts.Node) => ts.canHaveModifiers(node) && ts.getModifiers(node)?.some((item) => item.kind === ts.SyntaxKind.ExportKeyword); + const declarations = source.statements.filter(hasExport); + const assignments = source.statements.filter(ts.isExportAssignment); + const reexports = source.statements.filter(ts.isExportDeclaration); + const runtimeNames = declarations.flatMap((node) => { + if (ts.isTypeAliasDeclaration(node) || ts.isInterfaceDeclaration(node)) return []; + if (ts.getModifiers(node as ts.HasModifiers)?.some((item) => item.kind === ts.SyntaxKind.DefaultKeyword)) return ["default"]; + if (ts.isVariableStatement(node)) return node.declarationList.declarations.map((item) => item.name.getText(source)); + if (ts.isClassDeclaration(node) || ts.isFunctionDeclaration(node) || ts.isEnumDeclaration(node) || ts.isModuleDeclaration(node)) return [node.name?.getText(source) ?? "default"]; + return []; + }); + runtimeNames.push(...assignments.map(() => "default")); + for (const statement of reexports) { + if (!statement.isTypeOnly && statement.exportClause && ts.isNamedExports(statement.exportClause)) { + runtimeNames.push(...statement.exportClause.elements.filter((item) => !item.isTypeOnly).map((item) => item.name.text)); + } + } + expect(runtimeNames.sort(), `${path} changed its reviewed public exports`).toEqual(exception.runtimeExports); + if (["test", "entrypoint", "types"].includes(exception.role)) { + expect(declarations.every((node) => ts.isTypeAliasDeclaration(node) || ts.isInterfaceDeclaration(node)), path).toBe(true); + expect(assignments, path).toHaveLength(0); + expect(reexports, path).toHaveLength(0); + } else if (exception.role === "barrel") { + expect(source.statements.every((node) => ts.isExportDeclaration(node) && !node.exportClause && + node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text.startsWith(".")), path).toBe(true); + } else if (["schema", "data", "class"].includes(exception.role)) { + const runtime = declarations.filter((node) => !ts.isTypeAliasDeclaration(node) && !ts.isInterfaceDeclaration(node)); + expect(runtime, path).toHaveLength(1); + expect(assignments, path).toHaveLength(0); + expect(reexports, path).toHaveLength(0); + const declaration = runtime[0]!; + if (exception.role === "class") { + expect(ts.isClassDeclaration(declaration), path).toBe(true); + if (ts.isClassDeclaration(declaration)) expect(declaration.name?.text, path).toBe(basename(path, ".ts")); + } else { + expect(ts.isVariableStatement(declaration), path).toBe(true); + if (ts.isVariableStatement(declaration)) { + expect(declaration.declarationList.declarations, path).toHaveLength(1); + const variable = declaration.declarationList.declarations[0]!; + expect(variable.name.getText(source), path).toBe(basename(path).replace(/\.[^.]+$/, "")); + expect(variable.initializer && (ts.isArrowFunction(variable.initializer) || ts.isFunctionExpression(variable.initializer)), path).toBe(false); + } + } + } else { + expect(["framework", "generated"], path).toContain(exception.role); + expect(declarations.some((node) => ts.isFunctionDeclaration(node) || (ts.isVariableStatement(node) && + node.declarationList.declarations.some((item) => item.initializer && (ts.isArrowFunction(item.initializer) || ts.isFunctionExpression(item.initializer))))), path).toBe(false); + } + } + }; + await visit(definition.structure.root.children); + expect([...used].sort()).toEqual(Object.keys(coverage.exceptions).sort()); + }); + + it("keeps focused CLI and Schema contracts identical to their root contract subtrees", async () => { + const document = JSON.parse(await readFile(resolve(root, "anatomy.json"), "utf8")); + const subtree = (path: string) => path.split("/").reduce((nodes, name) => nodes.find((node: { name: { value: string } }) => node.name.value === name).children, document.structure.root.children); + for (const [path, contract] of [ + ["apps/anatomy-cli/src", "apps/anatomy-cli/anatomies/cli-source.anatomy.json"], + ["packages/schemas", "packages/schemas/anatomy.json"], + ]) { + const focused = JSON.parse(await readFile(resolve(root, contract!), "utf8")); + expect(focused.structure.root.children).toEqual(subtree(path!)); + } + }); +}); diff --git a/apps/anatomy-cli/src/cli.ts b/apps/anatomy-cli/src/runAnatomyCli.ts similarity index 75% rename from apps/anatomy-cli/src/cli.ts rename to apps/anatomy-cli/src/runAnatomyCli.ts index 8439d45..3aab14e 100644 --- a/apps/anatomy-cli/src/cli.ts +++ b/apps/anatomy-cli/src/runAnatomyCli.ts @@ -1,23 +1,19 @@ -import { err, ok, type Result } from "neverthrow"; import { checkAnatomy, planAnatomyCheck, queryAnatomy, type AnatomyFileTreeEntry } from "@anatomy-cli/anatomy/core"; import type { AnatomyDraftInput } from "@anatomy-cli/schemas"; -import { AnatomyCliUsage, parseCliArguments, type AnatomyCliOptions } from "./cli-arguments"; -import { - collectFileTree, - findAnatomyDefinition, - readAnatomyDefinition, - AnatomyDefinitionFileError, - type AnatomyFileTreeError, -} from "./filesystem"; -import { formatHumanResult } from "./format-result"; -import { formatAgentCheck, formatAgentQuery } from "./format-agent-result"; -import { collectSourceExports } from "./collect-source-exports"; - -export const AnatomyCliExitCode = { - success: 0, - blocked: 1, - operationalError: 2, -} as const; +import { err, ok, type Result } from "neverthrow"; +import { AnatomyCliExitCode } from "./AnatomyCliExitCode"; +import { AnatomyCliUsage } from "./AnatomyCliUsage"; +import { AnatomyDefinitionFileError } from "./AnatomyDefinitionFileError"; +import { type AnatomyFileTreeError } from "./AnatomyFileTreeError"; +import { collectSourceExports } from "./collectSourceExports"; +import { collectFileTree } from "./collectFileTree"; +import { collectGitFileTree } from "./collectGitFileTree"; +import { findAnatomyDefinition } from "./findAnatomyDefinition"; +import { formatAgentCheck } from "./formatAgentCheck"; +import { formatAgentQuery } from "./formatAgentQuery"; +import { formatHumanResult } from "./formatHumanResult"; +import { parseCliArguments, type AnatomyCliOptions } from "./parseCliArguments"; +import { readAnatomyDefinition } from "./readAnatomyDefinition"; export type AnatomyCliError = Error | AnatomyDefinitionFileError | AnatomyFileTreeError; @@ -32,6 +28,7 @@ export type AnatomyCliDependencies = { ) => Promise>; writeOutput: (value: string) => void; collectExports?: typeof collectSourceExports; + collectGitTree?: typeof collectGitFileTree; }; const defaultDependencies: AnatomyCliDependencies = { @@ -63,7 +60,9 @@ export const runAnatomyCli = async ( const definition = await dependencies.readDefinition(definitionPath.value); if (definition.isErr()) return err(definition.error); - const tree = await dependencies.collectTree(options.targetPath, options.ignore); + const tree = options.gitFiles + ? await (dependencies.collectGitTree ?? collectGitFileTree)(options.targetPath) + : await dependencies.collectTree(options.targetPath, options.ignore); if (tree.isErr()) return err(tree.error); if (options.queryPath !== null) { @@ -96,7 +95,7 @@ export const runAnatomyCli = async ( dependencies.writeOutput( options.format === "json" ? formatAgentCheck(checked.value, definition.value, - definitionPath.value, options.targetPath, tree.value, options.ignore) : formatHumanResult(checked.value), + definitionPath.value, options.targetPath, tree.value, options.ignore, options.gitFiles) : formatHumanResult(checked.value), ); return ok(checked.value.conforms ? AnatomyCliExitCode.success : AnatomyCliExitCode.blocked); diff --git a/apps/anatomy-cli/src/install.ts b/apps/anatomy-cli/src/runInstallation.ts similarity index 92% rename from apps/anatomy-cli/src/install.ts rename to apps/anatomy-cli/src/runInstallation.ts index 076f4fa..1122b24 100644 --- a/apps/anatomy-cli/src/install.ts +++ b/apps/anatomy-cli/src/runInstallation.ts @@ -1,11 +1,16 @@ -import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs"; +import { err, ok, Result } from "neverthrow"; import { spawnSync } from "node:child_process"; +import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"; import { join } from "node:path"; -import { err, ok, Result } from "neverthrow"; -import { AnatomyInstallError, type InstallOptions } from "./install-options"; -import { configurePath, getPathPlan } from "./install-path"; +import { AnatomyInstallError } from "./AnatomyInstallError"; +import { configurePath } from "./configurePath"; +import { getPathPlan } from "./getPathPlan"; +import { type InstallOptions } from "./parseInstallOptions"; +import { posixLauncher } from "./posixLauncher"; +import { windowsLauncher } from "./windowsLauncher"; const markerName = "install.json"; + const owner = "anatomy-cli/installer-v1"; export type InstallContext = { @@ -17,9 +22,6 @@ export type InstallContext = { env: NodeJS.ProcessEnv; }; -export const posixLauncher = '#!/bin/sh\nexec node "$(dirname "$0")/../anatomy.mjs" "$@"\n'; -export const windowsLauncher = '@echo off\r\nnode "%~dp0..\\anatomy.mjs" %*\r\nexit /b %errorlevel%\r\n'; - export const runInstallation = ( options: InstallOptions, context: InstallContext, diff --git a/apps/anatomy-cli/src/source-contract.spec.ts b/apps/anatomy-cli/src/source-contract.spec.ts index a9a1eef..66f08d1 100644 --- a/apps/anatomy-cli/src/source-contract.spec.ts +++ b/apps/anatomy-cli/src/source-contract.spec.ts @@ -1,8 +1,9 @@ +import { checkAnatomy, planAnatomyCheck } from "@anatomy-cli/anatomy/core"; import { resolve } from "node:path"; import { describe, expect, it } from "vitest"; -import { checkAnatomy, planAnatomyCheck } from "@anatomy-cli/anatomy/core"; -import { collectFileTree, readAnatomyDefinition } from "./filesystem"; -import { collectSourceExports } from "./collect-source-exports"; +import { collectSourceExports } from "./collectSourceExports"; +import { collectFileTree } from "./collectFileTree"; +import { readAnatomyDefinition } from "./readAnatomyDefinition"; describe("CLI source contract", () => { it("checks the real source directory against the shipped example definition", async () => { @@ -17,7 +18,7 @@ describe("CLI source contract", () => { expect(result.issues).toEqual([]); expect(result.conforms).toBe(true); - expect(checkAnatomy(definition, entries.filter((entry) => entry.name !== "cli.ts"), exports) + expect(checkAnatomy(definition, entries.filter((entry) => entry.name !== "runAnatomyCli.ts"), exports) ._unsafeUnwrap().conforms).toBe(false); expect(checkAnatomy(definition, [...entries, { kind: "file", name: "undeclared.ts" }], exports) ._unsafeUnwrap().conforms).toBe(false); diff --git a/apps/anatomy-cli/src/windowsLauncher.ts b/apps/anatomy-cli/src/windowsLauncher.ts new file mode 100644 index 0000000..790f803 --- /dev/null +++ b/apps/anatomy-cli/src/windowsLauncher.ts @@ -0,0 +1 @@ +export const windowsLauncher = '@echo off\r\nnode "%~dp0..\\anatomy.mjs" %*\r\nexit /b %errorlevel%\r\n'; diff --git a/apps/anatomy-cli/src/windowsPathScript.ts b/apps/anatomy-cli/src/windowsPathScript.ts new file mode 100644 index 0000000..5f6f6a6 --- /dev/null +++ b/apps/anatomy-cli/src/windowsPathScript.ts @@ -0,0 +1,7 @@ +export const windowsPathScript = [ + '$ErrorActionPreference = "Stop"', + '$bin = $env:ANATOMY_INSTALL_BIN', + '$current = [Environment]::GetEnvironmentVariable("Path", "User")', + '$entries = @($current -split ";" | Where-Object { $_ -and $_.TrimEnd("\\") -ine $bin.TrimEnd("\\") })', + '[Environment]::SetEnvironmentVariable("Path", ((@($bin) + $entries) -join ";"), "User")', +].join("; "); diff --git a/apps/docs/package.json b/apps/docs/package.json index 47206c0..31e68a1 100644 --- a/apps/docs/package.json +++ b/apps/docs/package.json @@ -38,6 +38,7 @@ "i18next-browser-languagedetector": "^8.2.1", "lucide-react": "^1.7.0", "motion": "^13.2.0", + "neverthrow": "^8.2.0", "nitro": "3.0.260429-beta", "payload": "4.0.0-canary.29", "react": "19.2.8", diff --git a/apps/docs/scripts/check-cloudflare-build.ts b/apps/docs/scripts/check-cloudflare-build.ts index 05c9eae..4573131 100644 --- a/apps/docs/scripts/check-cloudflare-build.ts +++ b/apps/docs/scripts/check-cloudflare-build.ts @@ -1,6 +1,6 @@ import assert from "node:assert/strict"; import { readFile } from "node:fs/promises"; -import { docsEntries } from "../src/content"; +import { docsEntries } from "../src/docsEntries"; const publicDirectory = new URL("../.output/public/", import.meta.url); const pages = ["index.html", ...docsEntries.map(({ slug }) => `docs/${slug}/index.html`)]; diff --git a/apps/docs/src/components/AppBootScreen/AppBootScreen.lifecycle.test.tsx b/apps/docs/src/components/AppBootScreen/AppBootScreen.lifecycle.test.tsx index b068a04..8e2b367 100644 --- a/apps/docs/src/components/AppBootScreen/AppBootScreen.lifecycle.test.tsx +++ b/apps/docs/src/components/AppBootScreen/AppBootScreen.lifecycle.test.tsx @@ -21,8 +21,9 @@ vi.mock("react", async (original) => ({ return [typeof initial === "function" ? initial() : initial, setter]; }, })); -vi.mock("@/lib/i18n", () => ({ applySavedLanguage: hooks.language })); -vi.mock("@/lib/theme", () => ({ applyTheme: hooks.theme, getSavedTheme: () => "dark" })); +vi.mock("@/lib/applySavedLanguage", () => ({ applySavedLanguage: hooks.language })); +vi.mock("@/lib/applyTheme", () => ({ applyTheme: hooks.theme })); +vi.mock("@/lib/getSavedTheme", () => ({ getSavedTheme: () => "dark" })); const deferred = () => { let resolve!: () => void; diff --git a/apps/docs/src/components/AppBootScreen/AppBootScreen.test.tsx b/apps/docs/src/components/AppBootScreen/AppBootScreen.test.tsx index 73e5dd0..61de339 100644 --- a/apps/docs/src/components/AppBootScreen/AppBootScreen.test.tsx +++ b/apps/docs/src/components/AppBootScreen/AppBootScreen.test.tsx @@ -1,6 +1,11 @@ import { afterEach, describe, expect, it, vi } from "vitest"; -import { createBootGeometry, getOpeningScale, TRIANGLE_VERTICES, type Point } from "./boot-geometry"; -import { BOOT_MOTION, createBootMotion, getTurnSettleMs, waitForBoot } from "./boot-motion"; +import { BOOT_MOTION } from "./BOOT_MOTION"; +import { createBootGeometry } from "./createBootGeometry"; +import { createBootMotion } from "./createBootMotion"; +import { getOpeningScale } from "./getOpeningScale"; +import { getTurnSettleMs } from "./getTurnSettleMs"; +import { TRIANGLE_VERTICES, type Point } from "./TRIANGLE_VERTICES"; +import { waitForBoot } from "./waitForBoot"; const contains = (polygon: Point[], point: Point) => { let inside = false; diff --git a/apps/docs/src/components/AppBootScreen/AppBootScreen.tsx b/apps/docs/src/components/AppBootScreen/AppBootScreen.tsx index 2a7b501..bd6ddac 100644 --- a/apps/docs/src/components/AppBootScreen/AppBootScreen.tsx +++ b/apps/docs/src/components/AppBootScreen/AppBootScreen.tsx @@ -1,8 +1,12 @@ +import { applySavedLanguage } from "@/lib/applySavedLanguage"; +import { applyTheme } from "@/lib/applyTheme"; +import { getSavedTheme } from "@/lib/getSavedTheme"; import { useEffect, useRef, useState } from "react"; -import { applySavedLanguage } from "@/lib/i18n"; -import { applyTheme, getSavedTheme } from "@/lib/theme"; -import { createBootGeometry, polygonPoints, TRIANGLE_VERTICES } from "./boot-geometry"; -import { createBootMotion, waitForBoot } from "./boot-motion"; +import { createBootGeometry } from "./createBootGeometry"; +import { createBootMotion } from "./createBootMotion"; +import { polygonPoints } from "./polygonPoints"; +import { TRIANGLE_VERTICES } from "./TRIANGLE_VERTICES"; +import { waitForBoot } from "./waitForBoot"; const MINIMUM_OPENING_MS = 640; const MAXIMUM_FONT_WAIT_MS = 900; diff --git a/apps/docs/src/components/AppBootScreen/BOOT_MOTION.ts b/apps/docs/src/components/AppBootScreen/BOOT_MOTION.ts new file mode 100644 index 0000000..ad8efcc --- /dev/null +++ b/apps/docs/src/components/AppBootScreen/BOOT_MOTION.ts @@ -0,0 +1,8 @@ +export const BOOT_MOTION = { + turnMs: 500, + holdFraction: 0.3, + landingFraction: 0.86, + raysMs: 560, + raysHoldMs: 100, + openingMs: 960, +} as const; diff --git a/apps/docs/src/components/AppBootScreen/OVERSCAN.ts b/apps/docs/src/components/AppBootScreen/OVERSCAN.ts new file mode 100644 index 0000000..ec8f4cb --- /dev/null +++ b/apps/docs/src/components/AppBootScreen/OVERSCAN.ts @@ -0,0 +1 @@ +export const OVERSCAN = 48; diff --git a/apps/docs/src/components/AppBootScreen/TRIANGLE_INRADIUS.ts b/apps/docs/src/components/AppBootScreen/TRIANGLE_INRADIUS.ts new file mode 100644 index 0000000..e22668e --- /dev/null +++ b/apps/docs/src/components/AppBootScreen/TRIANGLE_INRADIUS.ts @@ -0,0 +1,3 @@ +import { TRIANGLE_RADIUS } from "./TRIANGLE_RADIUS"; + +export const TRIANGLE_INRADIUS = TRIANGLE_RADIUS / 2; diff --git a/apps/docs/src/components/AppBootScreen/TRIANGLE_RADIUS.ts b/apps/docs/src/components/AppBootScreen/TRIANGLE_RADIUS.ts new file mode 100644 index 0000000..944d6a5 --- /dev/null +++ b/apps/docs/src/components/AppBootScreen/TRIANGLE_RADIUS.ts @@ -0,0 +1 @@ +export const TRIANGLE_RADIUS = 16; diff --git a/apps/docs/src/components/AppBootScreen/TRIANGLE_VERTICES.ts b/apps/docs/src/components/AppBootScreen/TRIANGLE_VERTICES.ts new file mode 100644 index 0000000..7dfc93c --- /dev/null +++ b/apps/docs/src/components/AppBootScreen/TRIANGLE_VERTICES.ts @@ -0,0 +1,12 @@ +import { TRIANGLE_INRADIUS } from "./TRIANGLE_INRADIUS"; +import { TRIANGLE_RADIUS } from "./TRIANGLE_RADIUS"; + +export type Point = { x: number; y: number }; + +const HALF_SIDE = (Math.sqrt(3) * TRIANGLE_RADIUS) / 2; + +export const TRIANGLE_VERTICES: Point[] = [ + { x: -HALF_SIDE, y: -TRIANGLE_INRADIUS }, + { x: HALF_SIDE, y: -TRIANGLE_INRADIUS }, + { x: 0, y: TRIANGLE_RADIUS }, +]; diff --git a/apps/docs/src/components/AppBootScreen/boot-geometry.ts b/apps/docs/src/components/AppBootScreen/createBootGeometry.ts similarity index 67% rename from apps/docs/src/components/AppBootScreen/boot-geometry.ts rename to apps/docs/src/components/AppBootScreen/createBootGeometry.ts index e769ebc..1a03b1a 100644 --- a/apps/docs/src/components/AppBootScreen/boot-geometry.ts +++ b/apps/docs/src/components/AppBootScreen/createBootGeometry.ts @@ -1,20 +1,5 @@ -export type Point = { x: number; y: number }; - -export const TRIANGLE_RADIUS = 16; -export const TRIANGLE_INRADIUS = TRIANGLE_RADIUS / 2; -const HALF_SIDE = (Math.sqrt(3) * TRIANGLE_RADIUS) / 2; -const OVERSCAN = 48; - -export const TRIANGLE_VERTICES: Point[] = [ - { x: -HALF_SIDE, y: -TRIANGLE_INRADIUS }, - { x: HALF_SIDE, y: -TRIANGLE_INRADIUS }, - { x: 0, y: TRIANGLE_RADIUS }, -]; - -export const polygonPoints = (points: Point[]) => points.map(({ x, y }) => `${x},${y}`).join(" "); - -export const getOpeningScale = (width: number, height: number) => - (Math.hypot(width, height) / 2 + OVERSCAN) / TRIANGLE_INRADIUS; +import { OVERSCAN } from "./OVERSCAN"; +import { TRIANGLE_VERTICES, type Point } from "./TRIANGLE_VERTICES"; export const createBootGeometry = (width: number, height: number) => { const [a, b, c] = TRIANGLE_VERTICES as [Point, Point, Point]; diff --git a/apps/docs/src/components/AppBootScreen/boot-motion.ts b/apps/docs/src/components/AppBootScreen/createBootMotion.ts similarity index 71% rename from apps/docs/src/components/AppBootScreen/boot-motion.ts rename to apps/docs/src/components/AppBootScreen/createBootMotion.ts index 7aa5406..8db8f82 100644 --- a/apps/docs/src/components/AppBootScreen/boot-motion.ts +++ b/apps/docs/src/components/AppBootScreen/createBootMotion.ts @@ -1,34 +1,7 @@ -import { getOpeningScale } from "./boot-geometry"; - -export const BOOT_MOTION = { - turnMs: 500, - holdFraction: 0.3, - landingFraction: 0.86, - raysMs: 560, - raysHoldMs: 100, - openingMs: 960, -} as const; - -export const getTurnSettleMs = (elapsedMs: number) => { - const position = elapsedMs % BOOT_MOTION.turnMs; - return position > BOOT_MOTION.turnMs * BOOT_MOTION.holdFraction - ? BOOT_MOTION.turnMs - position - : 0; -}; - -export const waitForBoot = (duration: number, signal: AbortSignal) => - new Promise((resolve, reject) => { - signal.throwIfAborted(); - const cancel = () => { - window.clearTimeout(timer); - reject(signal.reason); - }; - const timer = window.setTimeout(() => { - signal.removeEventListener("abort", cancel); - resolve(); - }, duration); - signal.addEventListener("abort", cancel, { once: true }); - }); +import { BOOT_MOTION } from "./BOOT_MOTION"; +import { getOpeningScale } from "./getOpeningScale"; +import { getTurnSettleMs } from "./getTurnSettleMs"; +import { waitForBoot } from "./waitForBoot"; export const createBootMotion = (screen: HTMLElement, signal: AbortSignal) => { const animations = new Set(); diff --git a/apps/docs/src/components/AppBootScreen/getOpeningScale.ts b/apps/docs/src/components/AppBootScreen/getOpeningScale.ts new file mode 100644 index 0000000..a083f09 --- /dev/null +++ b/apps/docs/src/components/AppBootScreen/getOpeningScale.ts @@ -0,0 +1,5 @@ +import { OVERSCAN } from "./OVERSCAN"; +import { TRIANGLE_INRADIUS } from "./TRIANGLE_INRADIUS"; + +export const getOpeningScale = (width: number, height: number) => + (Math.hypot(width, height) / 2 + OVERSCAN) / TRIANGLE_INRADIUS; diff --git a/apps/docs/src/components/AppBootScreen/getTurnSettleMs.ts b/apps/docs/src/components/AppBootScreen/getTurnSettleMs.ts new file mode 100644 index 0000000..1715d8b --- /dev/null +++ b/apps/docs/src/components/AppBootScreen/getTurnSettleMs.ts @@ -0,0 +1,8 @@ +import { BOOT_MOTION } from "./BOOT_MOTION"; + +export const getTurnSettleMs = (elapsedMs: number) => { + const position = elapsedMs % BOOT_MOTION.turnMs; + return position > BOOT_MOTION.turnMs * BOOT_MOTION.holdFraction + ? BOOT_MOTION.turnMs - position + : 0; +}; diff --git a/apps/docs/src/components/AppBootScreen/index.ts b/apps/docs/src/components/AppBootScreen/index.ts new file mode 100644 index 0000000..c609f74 --- /dev/null +++ b/apps/docs/src/components/AppBootScreen/index.ts @@ -0,0 +1,12 @@ +export * from "./AppBootScreen"; +export * from "./BOOT_MOTION"; +export * from "./OVERSCAN"; +export * from "./TRIANGLE_INRADIUS"; +export * from "./TRIANGLE_RADIUS"; +export * from "./TRIANGLE_VERTICES"; +export * from "./createBootGeometry"; +export * from "./createBootMotion"; +export * from "./getOpeningScale"; +export * from "./getTurnSettleMs"; +export * from "./polygonPoints"; +export * from "./waitForBoot"; diff --git a/apps/docs/src/components/AppBootScreen/polygonPoints.ts b/apps/docs/src/components/AppBootScreen/polygonPoints.ts new file mode 100644 index 0000000..f0fd002 --- /dev/null +++ b/apps/docs/src/components/AppBootScreen/polygonPoints.ts @@ -0,0 +1,3 @@ +import { type Point } from "./TRIANGLE_VERTICES"; + +export const polygonPoints = (points: Point[]) => points.map(({ x, y }) => `${x},${y}`).join(" "); diff --git a/apps/docs/src/components/AppBootScreen/waitForBoot.ts b/apps/docs/src/components/AppBootScreen/waitForBoot.ts new file mode 100644 index 0000000..7bb7df2 --- /dev/null +++ b/apps/docs/src/components/AppBootScreen/waitForBoot.ts @@ -0,0 +1,13 @@ +export const waitForBoot = (duration: number, signal: AbortSignal) => + new Promise((resolve, reject) => { + signal.throwIfAborted(); + const cancel = () => { + window.clearTimeout(timer); + reject(signal.reason); + }; + const timer = window.setTimeout(() => { + signal.removeEventListener("abort", cancel); + resolve(); + }, duration); + signal.addEventListener("abort", cancel, { once: true }); + }); diff --git a/apps/docs/src/components/LanguageSwitcher/LanguageSwitcher.tsx b/apps/docs/src/components/LanguageSwitcher/LanguageSwitcher.tsx index b995b23..b8ad6d2 100644 --- a/apps/docs/src/components/LanguageSwitcher/LanguageSwitcher.tsx +++ b/apps/docs/src/components/LanguageSwitcher/LanguageSwitcher.tsx @@ -1,7 +1,7 @@ import { Select } from "@base-ui/react/select"; import { Check, ChevronDown, Languages } from "lucide-react"; import { useTranslation } from "react-i18next"; -import { cn } from "@/lib/utils"; +import { cn } from "@/lib/cn"; const LANGUAGES = [ { value: "zh", labelKey: "common.chinese" }, diff --git a/apps/docs/src/components/MonoBlockCanvas/MonoBlockCanvas.tsx b/apps/docs/src/components/MonoBlockCanvas/MonoBlockCanvas.tsx index f2470c4..b39b942 100644 --- a/apps/docs/src/components/MonoBlockCanvas/MonoBlockCanvas.tsx +++ b/apps/docs/src/components/MonoBlockCanvas/MonoBlockCanvas.tsx @@ -1,5 +1,5 @@ import { useEffect, useRef, useState } from "react"; -import { cn } from "@/lib/utils"; +import { cn } from "@/lib/cn"; const CANVAS_WIDTH = 720; const CANVAS_HEIGHT = 520; diff --git a/apps/docs/src/components/StartupHome/KiteDartPattern.tsx b/apps/docs/src/components/StartupHome/KiteDartPattern.tsx index a9288b2..499ee23 100644 --- a/apps/docs/src/components/StartupHome/KiteDartPattern.tsx +++ b/apps/docs/src/components/StartupHome/KiteDartPattern.tsx @@ -1,12 +1,14 @@ -import { createPenroseTiling, type Point } from "./rhombus"; import { useEffect, useId, useRef } from "react"; +import { createPenroseTiling, type Point } from "./createPenroseTiling"; +import { updateKiteDartHover } from "./updateKiteDartHover"; const tiles = createPenroseTiling({ variant: "kite-dart", radius: 1200, levels: 5 }); + const SVG_SCALE = 0.44; + const SVG_OFFSET_X = 410; -const SVG_OFFSET_Y = 230; -const DEFAULT_HOVER_RADIUS_PX = 150; +const SVG_OFFSET_Y = 230; type KiteDartPatternProps = { className?: string; @@ -59,39 +61,13 @@ const edgeToPathSegment = (edge: Edge) => { }; const edges = createEdges(); + const basePath = edges .filter((edge) => edge.visible) .map(edgeToPathSegment) .join(" "); -const glowPath = edges.map(edgeToPathSegment).join(" "); -export const updateKiteDartHover = ( - grid: HTMLElement, - clientX: number | null, - clientY: number | null, -) => { - if (clientX === null || clientY === null) return; - - const hoverRadius = - Number.parseFloat(getComputedStyle(grid).getPropertyValue("--grid-hover-radius")) || - DEFAULT_HOVER_RADIUS_PX; - - grid.querySelectorAll(".startup-grid-background__kite-dart").forEach((svg) => { - const transform = svg.getScreenCTM(); - if (!transform) return; - - const inverse = transform.inverse(); - const pointer = new DOMPoint(clientX, clientY).matrixTransform(inverse); - const scaleX = Math.hypot(transform.a, transform.b) || 1; - const scaleY = Math.hypot(transform.c, transform.d) || 1; - const gradient = svg.querySelector("[data-kite-glow-gradient]"); - if (gradient) { - gradient.setAttribute("cx", pointer.x.toFixed(3)); - gradient.setAttribute("cy", pointer.y.toFixed(3)); - gradient.setAttribute("r", (hoverRadius / Math.sqrt(scaleX * scaleY)).toFixed(3)); - } - }); -}; +const glowPath = edges.map(edgeToPathSegment).join(" "); export const KiteDartPattern = ({ className }: KiteDartPatternProps) => { const svgRef = useRef(null); @@ -145,5 +121,4 @@ export const KiteDartPattern = ({ className }: KiteDartPatternProps) => { ); }; - KiteDartPattern.displayName = "KiteDartPattern"; diff --git a/apps/docs/src/components/StartupHome/RhombusPattern.tsx b/apps/docs/src/components/StartupHome/RhombusPattern.tsx index 98c4a48..28f160c 100644 --- a/apps/docs/src/components/StartupHome/RhombusPattern.tsx +++ b/apps/docs/src/components/StartupHome/RhombusPattern.tsx @@ -1,4 +1,5 @@ -import { createRhombusTiling, pointsToSvg } from "./rhombus"; +import { createRhombusTiling } from "./createRhombusTiling"; +import { pointsToSvg } from "./pointsToSvg"; const rhombi = createRhombusTiling(); diff --git a/apps/docs/src/components/StartupHome/StartupGridBackground.tsx b/apps/docs/src/components/StartupHome/StartupGridBackground.tsx index 79beabc..cc815cd 100644 --- a/apps/docs/src/components/StartupHome/StartupGridBackground.tsx +++ b/apps/docs/src/components/StartupHome/StartupGridBackground.tsx @@ -1,7 +1,7 @@ import { motion, useReducedMotion } from "motion/react"; import { useEffect, useRef, useState, type ReactNode } from "react"; - import { KiteDartPattern } from "./KiteDartPattern"; +import { updateGridPatternHover } from "./updateGridPatternHover"; type StartupGridBackgroundProps = { gridRef: { current: HTMLDivElement | null }; @@ -19,8 +19,11 @@ export type StartupGridTransitionRequest = { }; const ROTATION_INTERVAL_MS = 16_000; + const REVEAL_DURATION_MS = 1_800; + const HOLD_DURATION_MS = ROTATION_INTERVAL_MS - REVEAL_DURATION_MS; + const DEFAULT_TRANSITION_ORIGIN: StartupGridTransitionOrigin = { x: 50, y: 50 }; type PatternDefinition = { @@ -48,24 +51,6 @@ const patterns: PatternDefinition[] = [ { key: "kite-dart", render: (className) => }, ]; -export const updateGridPatternHover = ( - grid: HTMLElement, - clientX: number | null, - clientY: number | null, -) => { - if (clientX === null || clientY === null) return; - - grid.querySelectorAll(".startup-grid-background__pattern").forEach((pattern) => { - const rect = pattern.getBoundingClientRect(); - if (!rect.width || !rect.height) return; - - const x = ((clientX - rect.left) / rect.width) * 100; - const y = ((clientY - rect.top) / rect.height) * 100; - pattern.style.setProperty("--grid-pattern-pointer-x", `${x.toFixed(3)}%`); - pattern.style.setProperty("--grid-pattern-pointer-y", `${y.toFixed(3)}%`); - }); -}; - type Transition = { from: number; to: number; @@ -179,5 +164,4 @@ export const StartupGridBackground = ({ ); }; - StartupGridBackground.displayName = "StartupGridBackground"; diff --git a/apps/docs/src/components/StartupHome/StartupHeader.tsx b/apps/docs/src/components/StartupHome/StartupHeader.tsx index 15931aa..d3c5a07 100644 --- a/apps/docs/src/components/StartupHome/StartupHeader.tsx +++ b/apps/docs/src/components/StartupHome/StartupHeader.tsx @@ -1,10 +1,12 @@ +import { LanguageSwitcher } from "@/components/LanguageSwitcher"; +import { Button } from "@/components/ui/Button"; +import { applyTheme } from "@/lib/applyTheme"; +import { getSavedTheme } from "@/lib/getSavedTheme"; +import { saveTheme } from "@/lib/saveTheme"; +import { Link } from "@tanstack/react-router"; import { Menu, Moon, Sun, X } from "lucide-react"; import { useEffect, useState } from "react"; import { useTranslation } from "react-i18next"; -import { Link } from "@tanstack/react-router"; -import { Button } from "@/components/ui/Button"; -import { LanguageSwitcher } from "@/components/LanguageSwitcher"; -import { applyTheme, getSavedTheme, saveTheme } from "@/lib/theme"; const route = (href: string) => href as never; diff --git a/apps/docs/src/components/StartupHome/StartupHero.tsx b/apps/docs/src/components/StartupHome/StartupHero.tsx index bcd8793..093143b 100644 --- a/apps/docs/src/components/StartupHome/StartupHero.tsx +++ b/apps/docs/src/components/StartupHome/StartupHero.tsx @@ -1,13 +1,10 @@ +import { Button } from "@/components/ui/Button"; import { CheckCircle2, Copy } from "lucide-react"; import { useEffect, useRef, useState, type MouseEvent } from "react"; import { useTranslation } from "react-i18next"; -import { Button } from "@/components/ui/Button"; -import { - StartupGridBackground, - updateGridPatternHover, - type StartupGridTransitionRequest, -} from "./StartupGridBackground"; -import { updateKiteDartHover } from "./KiteDartPattern"; +import { StartupGridBackground, type StartupGridTransitionRequest } from "./StartupGridBackground"; +import { updateGridPatternHover } from "./updateGridPatternHover"; +import { updateKiteDartHover } from "./updateKiteDartHover"; type PackageManager = "npm" | "pnpm" | "bun"; type HeroTitlePhase = "present" | "exit" | "enter-start"; diff --git a/apps/docs/src/components/StartupHome/StartupScanSection.tsx b/apps/docs/src/components/StartupHome/StartupScanSection.tsx index 9313b95..885806e 100644 --- a/apps/docs/src/components/StartupHome/StartupScanSection.tsx +++ b/apps/docs/src/components/StartupHome/StartupScanSection.tsx @@ -1,8 +1,9 @@ +import { cn } from "@/lib/cn"; import { AlertCircle, CheckCircle2 } from "lucide-react"; import { useState } from "react"; import { useTranslation } from "react-i18next"; -import { cn } from "@/lib/utils"; -import { scanRows, StructureScanPreview } from "./StructureScanPreview"; +import { scanRows } from "./scanRows"; +import { StructureScanPreview } from "./StructureScanPreview"; export const StartupScanSection = () => { const { t } = useTranslation(); diff --git a/apps/docs/src/components/StartupHome/StartupTerminalCase.test.tsx b/apps/docs/src/components/StartupHome/StartupTerminalCase.test.tsx index f700a4b..707e1ad 100644 --- a/apps/docs/src/components/StartupHome/StartupTerminalCase.test.tsx +++ b/apps/docs/src/components/StartupHome/StartupTerminalCase.test.tsx @@ -1,11 +1,13 @@ +import { CODE_PATH_MAP, createCodePathDots, getCodePathPoint } from "@/components/icons"; +import en from "@/locales/en.json"; +import zh from "@/locales/zh.json"; import { createElement } from "react"; import { renderToStaticMarkup } from "react-dom/server"; import { afterEach, describe, expect, it, vi } from "vitest"; -import en from "@/locales/en.json"; -import zh from "@/locales/zh.json"; -import { CODE_PATH_MAP, createCodePathDots, getCodePathPoint } from "@/components/icons"; +import { getTerminalDemoFrame } from "./getTerminalDemoFrame"; import { StartupTerminalCase } from "./StartupTerminalCase"; -import { getTerminalDemoFrame, TERMINAL_COMMAND, TERMINAL_DEMO_TIMING as timing } from "./terminalDemo"; +import { TERMINAL_COMMAND } from "./TERMINAL_COMMAND"; +import { TERMINAL_DEMO_TIMING as timing } from "./TERMINAL_DEMO_TIMING"; const motionPreferences = vi.hoisted(() => ({ reducedMotion: true })); diff --git a/apps/docs/src/components/StartupHome/StartupTerminalCase.tsx b/apps/docs/src/components/StartupHome/StartupTerminalCase.tsx index 00732e0..20b8c73 100644 --- a/apps/docs/src/components/StartupHome/StartupTerminalCase.tsx +++ b/apps/docs/src/components/StartupHome/StartupTerminalCase.tsx @@ -1,10 +1,10 @@ +import { CODE_PATH_LABELS, CODE_PATH_MAP, CodePathMapIcon } from "@/components/icons"; +import { cn } from "@/lib/cn"; import { CheckCircle2, Terminal } from "lucide-react"; import { useTranslation } from "react-i18next"; -import { CODE_PATH_LABELS, CODE_PATH_MAP, CodePathMapIcon } from "@/components/icons"; -import { cn } from "@/lib/utils"; -import { TERMINAL_COMMAND } from "./terminalDemo"; -import { useTerminalDemo } from "./useTerminalDemo"; import "./StartupTerminalCase.css"; +import { TERMINAL_COMMAND } from "./TERMINAL_COMMAND"; +import { useTerminalDemo } from "./useTerminalDemo"; export const StartupTerminalCase = () => { const { t } = useTranslation(); diff --git a/apps/docs/src/components/StartupHome/StructureScanPreview.tsx b/apps/docs/src/components/StartupHome/StructureScanPreview.tsx index ef86e9b..2ae50a5 100644 --- a/apps/docs/src/components/StartupHome/StructureScanPreview.tsx +++ b/apps/docs/src/components/StartupHome/StructureScanPreview.tsx @@ -1,29 +1,15 @@ +import { Button } from "@/components/ui/Button"; +import { cn } from "@/lib/cn"; import { - Braces, - CheckCircle2, - FileCode2, - Folder, - FolderOpen, +Braces, +CheckCircle2, +FileCode2, +FolderOpen } from "lucide-react"; import { useEffect, useRef, useState } from "react"; import { useTranslation } from "react-i18next"; -import { Button } from "@/components/ui/Button"; -import { cn } from "@/lib/utils"; import { StructureTreeRow } from "./StructureTreeRow"; - -export const scanRows = [ - { icon: FolderOpen, label: "src/", status: "pass" as const }, - { icon: Folder, label: "components/", indent: 1 as const, status: "pass" as const }, - { icon: Folder, label: "ui/", indent: 2 as const, status: "pass" as const }, - { icon: Folder, label: "routes/", indent: 1 as const, status: "pass" as const }, - { icon: FileCode2, label: "home.tsx", indent: 2 as const, status: "pass" as const }, - { icon: Folder, label: "lib/", indent: 1 as const, status: "pass" as const }, - { icon: FileCode2, label: "utils.ts", indent: 2 as const, status: "pass" as const }, - { icon: Folder, label: "hooks/", indent: 1 as const, status: "pass" as const }, - { icon: Folder, label: "assets/", indent: 1 as const, status: "pass" as const }, - { icon: Folder, label: "tests/", indent: 1 as const, status: "pass" as const }, - { icon: Folder, label: "legacy/", indent: 1 as const, status: "warn" as const }, -]; +import { scanRows } from "./scanRows"; const definitionExample = `{ "root": { @@ -233,5 +219,4 @@ export const StructureScanPreview = ({ onStageChange }: { onStageChange?: (stage ); }; - StructureScanPreview.displayName = "StructureScanPreview"; diff --git a/apps/docs/src/components/StartupHome/StructureTreeRow.tsx b/apps/docs/src/components/StartupHome/StructureTreeRow.tsx index ca0786c..fba3b7a 100644 --- a/apps/docs/src/components/StartupHome/StructureTreeRow.tsx +++ b/apps/docs/src/components/StartupHome/StructureTreeRow.tsx @@ -1,5 +1,5 @@ import { AlertCircle, CheckCircle2, type LucideIcon } from "lucide-react"; -import { cn } from "@/lib/utils"; +import { cn } from "@/lib/cn"; export type StructureTreeRowProps = { icon: LucideIcon; diff --git a/apps/docs/src/components/StartupHome/TERMINAL_COMMAND.ts b/apps/docs/src/components/StartupHome/TERMINAL_COMMAND.ts new file mode 100644 index 0000000..fe74ef9 --- /dev/null +++ b/apps/docs/src/components/StartupHome/TERMINAL_COMMAND.ts @@ -0,0 +1 @@ +export const TERMINAL_COMMAND = "anatomy ./src"; diff --git a/apps/docs/src/components/StartupHome/TERMINAL_DEMO_TIMING.ts b/apps/docs/src/components/StartupHome/TERMINAL_DEMO_TIMING.ts new file mode 100644 index 0000000..7b58777 --- /dev/null +++ b/apps/docs/src/components/StartupHome/TERMINAL_DEMO_TIMING.ts @@ -0,0 +1,10 @@ +export const TERMINAL_DEMO_TIMING = { + typeStart: 200, + character: 56, + block: 1_100, + fix: 2_300, + migration: 700, + recheck: 3_100, + pass: 4_100, + end: 4_600, +} as const; diff --git a/apps/docs/src/components/StartupHome/add.ts b/apps/docs/src/components/StartupHome/add.ts new file mode 100644 index 0000000..c6de1af --- /dev/null +++ b/apps/docs/src/components/StartupHome/add.ts @@ -0,0 +1,3 @@ +import { type Point } from "./createPenroseTiling"; + +export const add = (a: Point, b: Point): Point => [a[0] + b[0], a[1] + b[1]]; diff --git a/apps/docs/src/components/StartupHome/rhombus.ts b/apps/docs/src/components/StartupHome/createPenroseTiling.ts similarity index 84% rename from apps/docs/src/components/StartupHome/rhombus.ts rename to apps/docs/src/components/StartupHome/createPenroseTiling.ts index 8e473b3..eed551c 100644 --- a/apps/docs/src/components/StartupHome/rhombus.ts +++ b/apps/docs/src/components/StartupHome/createPenroseTiling.ts @@ -1,5 +1,9 @@ +import { add } from "./add"; + export type Point = readonly [number, number]; + export type PenroseVariant = "rhombus" | "kite-dart"; + export type PenroseTile = { id: string; kind: "thin" | "thick" | "kite" | "dart"; @@ -9,13 +13,17 @@ export type PenroseTile = { type Triangle = { kind: 0 | 1; a: Point; b: Point; c: Point }; const PHI = (1 + Math.sqrt(5)) / 2; + const INV_PHI = 1 / PHI; + const INV_PHI_SQUARED = INV_PHI * INV_PHI; const sub = (a: Point, b: Point): Point => [a[0] - b[0], a[1] - b[1]]; -const add = (a: Point, b: Point): Point => [a[0] + b[0], a[1] + b[1]]; + const scale = (a: Point, factor: number): Point => [a[0] * factor, a[1] * factor]; + const along = (a: Point, b: Point, factor: number): Point => add(a, scale(sub(b, a), factor)); + const pointKey = (point: Point): string => `${point[0].toFixed(5)},${point[1].toFixed(5)}`; const intersectsCenteredSquare = (triangle: Triangle, limit: number): boolean => { @@ -188,37 +196,3 @@ export const createPenroseTiling = ({ ); return mergeHalfTiles(triangles, variant === "rhombus" ? "base" : "axis", variant); }; - -export const pointsToSvg = (points: Point[], scaleFactor = 1, offset: Point = [410, 230]): string => - points - .map(([x, y]) => `${(x * scaleFactor + offset[0]).toFixed(2)},${(y * scaleFactor + offset[1]).toFixed(2)}`) - .join(" "); - -/** A deliberately simple 60°/120° edge-to-edge rhombus lattice for the hero. */ -export const createRhombusTiling = ({ - columns = 28, - rows = 20, - size = 82, -}: { - columns?: number; - rows?: number; - size?: number; -} = {}): PenroseTile[] => { - const diagonal: Point = [size * 0.5, size * (Math.sqrt(3) / 2)]; - return Array.from({ length: rows }, (_, row) => - Array.from({ length: columns }, (_, column) => { - const origin: Point = [ - (column - (columns - 1) / 2) * size + (row - (rows - 1) / 2) * diagonal[0], - (row - (rows - 1) / 2) * diagonal[1], - ]; - const top = add(origin, [size, 0]); - const right = add(top, diagonal); - const left = add(origin, diagonal); - return { - id: `rhombus-${row}-${column}`, - kind: "thin" as const, - points: [origin, top, right, left], - }; - }), - ).flat(); -}; diff --git a/apps/docs/src/components/StartupHome/createRhombusTiling.ts b/apps/docs/src/components/StartupHome/createRhombusTiling.ts new file mode 100644 index 0000000..b4ac234 --- /dev/null +++ b/apps/docs/src/components/StartupHome/createRhombusTiling.ts @@ -0,0 +1,30 @@ +import { add } from "./add"; +import { type PenroseTile, type Point } from "./createPenroseTiling"; + +export const createRhombusTiling = ({ + columns = 28, + rows = 20, + size = 82, +}: { + columns?: number; + rows?: number; + size?: number; +} = {}): PenroseTile[] => { + const diagonal: Point = [size * 0.5, size * (Math.sqrt(3) / 2)]; + return Array.from({ length: rows }, (_, row) => + Array.from({ length: columns }, (_, column) => { + const origin: Point = [ + (column - (columns - 1) / 2) * size + (row - (rows - 1) / 2) * diagonal[0], + (row - (rows - 1) / 2) * diagonal[1], + ]; + const top = add(origin, [size, 0]); + const right = add(top, diagonal); + const left = add(origin, diagonal); + return { + id: `rhombus-${row}-${column}`, + kind: "thin" as const, + points: [origin, top, right, left], + }; + }), + ).flat(); +}; diff --git a/apps/docs/src/components/StartupHome/terminalDemo.ts b/apps/docs/src/components/StartupHome/getTerminalDemoFrame.ts similarity index 80% rename from apps/docs/src/components/StartupHome/terminalDemo.ts rename to apps/docs/src/components/StartupHome/getTerminalDemoFrame.ts index ac94760..6856b3d 100644 --- a/apps/docs/src/components/StartupHome/terminalDemo.ts +++ b/apps/docs/src/components/StartupHome/getTerminalDemoFrame.ts @@ -1,15 +1,5 @@ -export const TERMINAL_COMMAND = "anatomy ./src"; - -export const TERMINAL_DEMO_TIMING = { - typeStart: 200, - character: 56, - block: 1_100, - fix: 2_300, - migration: 700, - recheck: 3_100, - pass: 4_100, - end: 4_600, -} as const; +import { TERMINAL_COMMAND } from "./TERMINAL_COMMAND"; +import { TERMINAL_DEMO_TIMING } from "./TERMINAL_DEMO_TIMING"; const typedCommand = (elapsed: number, start: number) => TERMINAL_COMMAND.slice(0, Math.max(0, Math.floor((elapsed - start) / TERMINAL_DEMO_TIMING.character))); diff --git a/apps/docs/src/components/StartupHome/index.ts b/apps/docs/src/components/StartupHome/index.ts index d05a8d2..ae64615 100644 --- a/apps/docs/src/components/StartupHome/index.ts +++ b/apps/docs/src/components/StartupHome/index.ts @@ -1,11 +1,14 @@ -export * from "./StartupHome"; +export * from "./KiteDartPattern"; +export * from "./RhombusPattern"; +export * from "./scanRows"; export * from "./StartupCta"; export * from "./StartupFooter"; export * from "./StartupGridBackground"; export * from "./StartupHeader"; export * from "./StartupHero"; -export * from "./StartupTerminalCase"; -export * from "./RhombusPattern"; -export * from "./KiteDartPattern"; +export * from "./StartupHome"; export * from "./StartupScanSection"; +export * from "./StartupTerminalCase"; export * from "./StructureScanPreview"; +export * from "./updateGridPatternHover"; +export * from "./updateKiteDartHover"; diff --git a/apps/docs/src/components/StartupHome/pointsToSvg.ts b/apps/docs/src/components/StartupHome/pointsToSvg.ts new file mode 100644 index 0000000..b690cff --- /dev/null +++ b/apps/docs/src/components/StartupHome/pointsToSvg.ts @@ -0,0 +1,6 @@ +import { type Point } from "./createPenroseTiling"; + +export const pointsToSvg = (points: Point[], scaleFactor = 1, offset: Point = [410, 230]): string => + points + .map(([x, y]) => `${(x * scaleFactor + offset[0]).toFixed(2)},${(y * scaleFactor + offset[1]).toFixed(2)}`) + .join(" "); diff --git a/apps/docs/src/components/StartupHome/scanRows.tsx b/apps/docs/src/components/StartupHome/scanRows.tsx new file mode 100644 index 0000000..da800a2 --- /dev/null +++ b/apps/docs/src/components/StartupHome/scanRows.tsx @@ -0,0 +1,19 @@ +import { +FileCode2, +Folder, +FolderOpen +} from "lucide-react"; + +export const scanRows = [ + { icon: FolderOpen, label: "src/", status: "pass" as const }, + { icon: Folder, label: "components/", indent: 1 as const, status: "pass" as const }, + { icon: Folder, label: "ui/", indent: 2 as const, status: "pass" as const }, + { icon: Folder, label: "routes/", indent: 1 as const, status: "pass" as const }, + { icon: FileCode2, label: "home.tsx", indent: 2 as const, status: "pass" as const }, + { icon: Folder, label: "lib/", indent: 1 as const, status: "pass" as const }, + { icon: FileCode2, label: "utils.ts", indent: 2 as const, status: "pass" as const }, + { icon: Folder, label: "hooks/", indent: 1 as const, status: "pass" as const }, + { icon: Folder, label: "assets/", indent: 1 as const, status: "pass" as const }, + { icon: Folder, label: "tests/", indent: 1 as const, status: "pass" as const }, + { icon: Folder, label: "legacy/", indent: 1 as const, status: "warn" as const }, +]; diff --git a/apps/docs/src/components/StartupHome/updateGridPatternHover.tsx b/apps/docs/src/components/StartupHome/updateGridPatternHover.tsx new file mode 100644 index 0000000..bfcd649 --- /dev/null +++ b/apps/docs/src/components/StartupHome/updateGridPatternHover.tsx @@ -0,0 +1,17 @@ +export const updateGridPatternHover = ( + grid: HTMLElement, + clientX: number | null, + clientY: number | null, +) => { + if (clientX === null || clientY === null) return; + + grid.querySelectorAll(".startup-grid-background__pattern").forEach((pattern) => { + const rect = pattern.getBoundingClientRect(); + if (!rect.width || !rect.height) return; + + const x = ((clientX - rect.left) / rect.width) * 100; + const y = ((clientY - rect.top) / rect.height) * 100; + pattern.style.setProperty("--grid-pattern-pointer-x", `${x.toFixed(3)}%`); + pattern.style.setProperty("--grid-pattern-pointer-y", `${y.toFixed(3)}%`); + }); +}; diff --git a/apps/docs/src/components/StartupHome/updateKiteDartHover.tsx b/apps/docs/src/components/StartupHome/updateKiteDartHover.tsx new file mode 100644 index 0000000..ac38965 --- /dev/null +++ b/apps/docs/src/components/StartupHome/updateKiteDartHover.tsx @@ -0,0 +1,29 @@ +const DEFAULT_HOVER_RADIUS_PX = 150; + +export const updateKiteDartHover = ( + grid: HTMLElement, + clientX: number | null, + clientY: number | null, +) => { + if (clientX === null || clientY === null) return; + + const hoverRadius = + Number.parseFloat(getComputedStyle(grid).getPropertyValue("--grid-hover-radius")) || + DEFAULT_HOVER_RADIUS_PX; + + grid.querySelectorAll(".startup-grid-background__kite-dart").forEach((svg) => { + const transform = svg.getScreenCTM(); + if (!transform) return; + + const inverse = transform.inverse(); + const pointer = new DOMPoint(clientX, clientY).matrixTransform(inverse); + const scaleX = Math.hypot(transform.a, transform.b) || 1; + const scaleY = Math.hypot(transform.c, transform.d) || 1; + const gradient = svg.querySelector("[data-kite-glow-gradient]"); + if (gradient) { + gradient.setAttribute("cx", pointer.x.toFixed(3)); + gradient.setAttribute("cy", pointer.y.toFixed(3)); + gradient.setAttribute("r", (hoverRadius / Math.sqrt(scaleX * scaleY)).toFixed(3)); + } + }); +}; diff --git a/apps/docs/src/components/StartupHome/useTerminalDemo.ts b/apps/docs/src/components/StartupHome/useTerminalDemo.ts index 3fb494c..657e7c4 100644 --- a/apps/docs/src/components/StartupHome/useTerminalDemo.ts +++ b/apps/docs/src/components/StartupHome/useTerminalDemo.ts @@ -1,6 +1,7 @@ import { useInView, useReducedMotion } from "motion/react"; import { useEffect, useRef, useState } from "react"; -import { getTerminalDemoFrame, TERMINAL_DEMO_TIMING } from "./terminalDemo"; +import { getTerminalDemoFrame } from "./getTerminalDemoFrame"; +import { TERMINAL_DEMO_TIMING } from "./TERMINAL_DEMO_TIMING"; export const useTerminalDemo = () => { const ref = useRef(null); diff --git a/apps/docs/src/components/icons/CODE_PATH_LABELS.ts b/apps/docs/src/components/icons/CODE_PATH_LABELS.ts new file mode 100644 index 0000000..6ba2da7 --- /dev/null +++ b/apps/docs/src/components/icons/CODE_PATH_LABELS.ts @@ -0,0 +1,7 @@ +export const CODE_PATH_LABELS = [ + { label: "src/legacy/", x: 112, y: 400, kind: "source" }, + { label: "src/components/ui/", x: 454, y: 216, kind: "destination" }, + { label: "routes/", x: 218, y: 84, kind: "context" }, + { label: "lib/", x: 551, y: 395, kind: "context" }, + { label: "tests/", x: 351, y: 480, kind: "context" }, +] as const; diff --git a/apps/docs/src/components/icons/CODE_PATH_MAP.ts b/apps/docs/src/components/icons/CODE_PATH_MAP.ts new file mode 100644 index 0000000..067696e --- /dev/null +++ b/apps/docs/src/components/icons/CODE_PATH_MAP.ts @@ -0,0 +1,7 @@ +export const CODE_PATH_MAP = { + width: 640, + height: 560, + start: { x: 112, y: 400 }, + control: { x: 250, y: 112 }, + end: { x: 454, y: 216 }, +} as const; diff --git a/apps/docs/src/components/icons/CODE_PATH_ROUTE.ts b/apps/docs/src/components/icons/CODE_PATH_ROUTE.ts new file mode 100644 index 0000000..880da7e --- /dev/null +++ b/apps/docs/src/components/icons/CODE_PATH_ROUTE.ts @@ -0,0 +1,3 @@ +import { CODE_PATH_MAP } from "./CODE_PATH_MAP"; + +export const CODE_PATH_ROUTE = `M ${CODE_PATH_MAP.start.x} ${CODE_PATH_MAP.start.y} Q ${CODE_PATH_MAP.control.x} ${CODE_PATH_MAP.control.y} ${CODE_PATH_MAP.end.x} ${CODE_PATH_MAP.end.y}`; diff --git a/apps/docs/src/components/icons/CodePathMapIcon.tsx b/apps/docs/src/components/icons/CodePathMapIcon.tsx index 50099dc..fe2a7f3 100644 --- a/apps/docs/src/components/icons/CodePathMapIcon.tsx +++ b/apps/docs/src/components/icons/CodePathMapIcon.tsx @@ -1,5 +1,9 @@ import { useId, type SVGProps } from "react"; -import { CODE_PATH_LABELS, CODE_PATH_MAP, CODE_PATH_ROUTE, createCodePathDots, getCodePathPoint } from "./codePathMap"; +import { CODE_PATH_LABELS } from "./CODE_PATH_LABELS"; +import { CODE_PATH_MAP } from "./CODE_PATH_MAP"; +import { CODE_PATH_ROUTE } from "./CODE_PATH_ROUTE"; +import { createCodePathDots } from "./createCodePathDots"; +import { getCodePathPoint } from "./getCodePathPoint"; export interface CodePathMapIconProps extends SVGProps { progress?: number; diff --git a/apps/docs/src/components/icons/codePathMap.ts b/apps/docs/src/components/icons/codePathMap.ts deleted file mode 100644 index 34c695a..0000000 --- a/apps/docs/src/components/icons/codePathMap.ts +++ /dev/null @@ -1,49 +0,0 @@ -export const CODE_PATH_MAP = { - width: 640, - height: 560, - start: { x: 112, y: 400 }, - control: { x: 250, y: 112 }, - end: { x: 454, y: 216 }, -} as const; - -export const CODE_PATH_ROUTE = `M ${CODE_PATH_MAP.start.x} ${CODE_PATH_MAP.start.y} Q ${CODE_PATH_MAP.control.x} ${CODE_PATH_MAP.control.y} ${CODE_PATH_MAP.end.x} ${CODE_PATH_MAP.end.y}`; - -export const CODE_PATH_LABELS = [ - { label: "src/legacy/", x: 112, y: 400, kind: "source" }, - { label: "src/components/ui/", x: 454, y: 216, kind: "destination" }, - { label: "routes/", x: 218, y: 84, kind: "context" }, - { label: "lib/", x: 551, y: 395, kind: "context" }, - { label: "tests/", x: 351, y: 480, kind: "context" }, -] as const; - -const islands = [ - { x: 110, y: 396, rx: 76, ry: 74 }, - { x: 215, y: 90, rx: 82, ry: 53 }, - { x: 452, y: 218, rx: 118, ry: 106 }, - { x: 552, y: 392, rx: 59, ry: 60 }, - { x: 350, y: 483, rx: 90, ry: 52 }, -]; - -export const createCodePathDots = () => { - const dots: { x: number; y: number; opacity: number }[] = []; - for (let y = 24; y < CODE_PATH_MAP.height - 12; y += 8) { - for (let x = 20; x < CODE_PATH_MAP.width - 12; x += 8) { - const distance = Math.min(...islands.map((island) => - ((x - island.x) / island.rx) ** 2 + ((y - island.y) / island.ry) ** 2)); - const edge = 0.93 + Math.sin(x * 0.055 + y * 0.023) * 0.12; - if (distance < edge) { - dots.push({ x, y, opacity: Math.max(0.16, 0.5 - distance * 0.3) }); - } - } - } - return dots; -}; - -export const getCodePathPoint = (progress: number) => { - const t = Math.min(1, Math.max(0, progress)); - const { start, control, end } = CODE_PATH_MAP; - return { - x: (1 - t) ** 2 * start.x + 2 * (1 - t) * t * control.x + t ** 2 * end.x, - y: (1 - t) ** 2 * start.y + 2 * (1 - t) * t * control.y + t ** 2 * end.y, - }; -}; diff --git a/apps/docs/src/components/icons/createCodePathDots.ts b/apps/docs/src/components/icons/createCodePathDots.ts new file mode 100644 index 0000000..2386618 --- /dev/null +++ b/apps/docs/src/components/icons/createCodePathDots.ts @@ -0,0 +1,24 @@ +import { CODE_PATH_MAP } from "./CODE_PATH_MAP"; + +const islands = [ + { x: 110, y: 396, rx: 76, ry: 74 }, + { x: 215, y: 90, rx: 82, ry: 53 }, + { x: 452, y: 218, rx: 118, ry: 106 }, + { x: 552, y: 392, rx: 59, ry: 60 }, + { x: 350, y: 483, rx: 90, ry: 52 }, +]; + +export const createCodePathDots = () => { + const dots: { x: number; y: number; opacity: number }[] = []; + for (let y = 24; y < CODE_PATH_MAP.height - 12; y += 8) { + for (let x = 20; x < CODE_PATH_MAP.width - 12; x += 8) { + const distance = Math.min(...islands.map((island) => + ((x - island.x) / island.rx) ** 2 + ((y - island.y) / island.ry) ** 2)); + const edge = 0.93 + Math.sin(x * 0.055 + y * 0.023) * 0.12; + if (distance < edge) { + dots.push({ x, y, opacity: Math.max(0.16, 0.5 - distance * 0.3) }); + } + } + } + return dots; +}; diff --git a/apps/docs/src/components/icons/getCodePathPoint.ts b/apps/docs/src/components/icons/getCodePathPoint.ts new file mode 100644 index 0000000..b2172a9 --- /dev/null +++ b/apps/docs/src/components/icons/getCodePathPoint.ts @@ -0,0 +1,10 @@ +import { CODE_PATH_MAP } from "./CODE_PATH_MAP"; + +export const getCodePathPoint = (progress: number) => { + const t = Math.min(1, Math.max(0, progress)); + const { start, control, end } = CODE_PATH_MAP; + return { + x: (1 - t) ** 2 * start.x + 2 * (1 - t) * t * control.x + t ** 2 * end.x, + y: (1 - t) ** 2 * start.y + 2 * (1 - t) * t * control.y + t ** 2 * end.y, + }; +}; diff --git a/apps/docs/src/components/icons/index.ts b/apps/docs/src/components/icons/index.ts index 4d3f858..6154915 100644 --- a/apps/docs/src/components/icons/index.ts +++ b/apps/docs/src/components/icons/index.ts @@ -1,2 +1,6 @@ +export * from "./CODE_PATH_LABELS"; +export * from "./CODE_PATH_MAP"; +export * from "./CODE_PATH_ROUTE"; export * from "./CodePathMapIcon"; -export * from "./codePathMap"; +export * from "./createCodePathDots"; +export * from "./getCodePathPoint"; diff --git a/apps/docs/src/components/ui/Badge/Badge.tsx b/apps/docs/src/components/ui/Badge/Badge.tsx index 130ebeb..f786498 100644 --- a/apps/docs/src/components/ui/Badge/Badge.tsx +++ b/apps/docs/src/components/ui/Badge/Badge.tsx @@ -1,5 +1,5 @@ import type { HTMLAttributes } from "react"; -import { cn } from "@/lib/utils"; +import { cn } from "@/lib/cn"; export type BadgeProps = HTMLAttributes; diff --git a/apps/docs/src/components/ui/Button/Button.tsx b/apps/docs/src/components/ui/Button/Button.tsx index d1f85d3..3154874 100644 --- a/apps/docs/src/components/ui/Button/Button.tsx +++ b/apps/docs/src/components/ui/Button/Button.tsx @@ -1,31 +1,7 @@ +import { cn } from "@/lib/cn"; import { Button as ButtonPrimitive } from "@base-ui/react/button"; import type { VariantProps } from "class-variance-authority"; -import { cva } from "class-variance-authority"; -import { cn } from "@/lib/utils"; - -export const buttonVariants = cva( - "inline-flex shrink-0 cursor-pointer items-center justify-center gap-2 rounded-md border font-medium outline-none transition-colors duration-150 focus-visible:ring-2 focus-visible:ring-[var(--ring)] disabled:pointer-events-none disabled:opacity-50", - { - variants: { - variant: { - default: - "border-[var(--primary)] bg-[var(--primary)] text-[var(--primary-foreground)] hover:brightness-110", - outline: - "border-[var(--border)] bg-transparent text-[var(--foreground)] hover:border-[var(--primary)] hover:bg-[var(--muted)]", - ghost: - "border-transparent bg-transparent text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--foreground)]", - link: "border-transparent bg-transparent text-[var(--primary)] underline-offset-4 hover:underline", - }, - size: { - default: "h-10 px-4 text-sm", - sm: "h-8 px-3 text-xs", - lg: "h-12 px-6 text-base", - icon: "size-9 p-0", - }, - }, - defaultVariants: { variant: "default", size: "default" }, - }, -); +import { buttonVariants } from "./buttonVariants"; export type ButtonProps = ButtonPrimitive.Props & VariantProps; @@ -41,5 +17,4 @@ export const Button = ({ {...props} /> ); - Button.displayName = "Button"; diff --git a/apps/docs/src/components/ui/Button/buttonVariants.tsx b/apps/docs/src/components/ui/Button/buttonVariants.tsx new file mode 100644 index 0000000..3c19855 --- /dev/null +++ b/apps/docs/src/components/ui/Button/buttonVariants.tsx @@ -0,0 +1,25 @@ +import { cva } from "class-variance-authority"; + +export const buttonVariants = cva( + "inline-flex shrink-0 cursor-pointer items-center justify-center gap-2 rounded-md border font-medium outline-none transition-colors duration-150 focus-visible:ring-2 focus-visible:ring-[var(--ring)] disabled:pointer-events-none disabled:opacity-50", + { + variants: { + variant: { + default: + "border-[var(--primary)] bg-[var(--primary)] text-[var(--primary-foreground)] hover:brightness-110", + outline: + "border-[var(--border)] bg-transparent text-[var(--foreground)] hover:border-[var(--primary)] hover:bg-[var(--muted)]", + ghost: + "border-transparent bg-transparent text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--foreground)]", + link: "border-transparent bg-transparent text-[var(--primary)] underline-offset-4 hover:underline", + }, + size: { + default: "h-10 px-4 text-sm", + sm: "h-8 px-3 text-xs", + lg: "h-12 px-6 text-base", + icon: "size-9 p-0", + }, + }, + defaultVariants: { variant: "default", size: "default" }, + }, +); diff --git a/apps/docs/src/components/ui/Button/index.ts b/apps/docs/src/components/ui/Button/index.ts index e22c29a..5823aa0 100644 --- a/apps/docs/src/components/ui/Button/index.ts +++ b/apps/docs/src/components/ui/Button/index.ts @@ -1 +1,2 @@ export * from "./Button"; +export * from "./buttonVariants"; diff --git a/apps/docs/src/components/ui/Card/Card.tsx b/apps/docs/src/components/ui/Card/Card.tsx index 5e5b54b..3bbfbd5 100644 --- a/apps/docs/src/components/ui/Card/Card.tsx +++ b/apps/docs/src/components/ui/Card/Card.tsx @@ -1,9 +1,7 @@ +import { cn } from "@/lib/cn"; import type { HTMLAttributes } from "react"; -import { cn } from "@/lib/utils"; export type CardProps = HTMLAttributes; -export type CardHeaderProps = HTMLAttributes; -export type CardContentProps = HTMLAttributes; export const Card = ({ className, ...props }: CardProps) => (
( {...props} /> ); -export const CardHeader = ({ className, ...props }: CardHeaderProps) => ( -
-); -export const CardContent = ({ className, ...props }: CardContentProps) => ( -
-); - Card.displayName = "Card"; -CardHeader.displayName = "CardHeader"; -CardContent.displayName = "CardContent"; diff --git a/apps/docs/src/components/ui/Card/CardContent.tsx b/apps/docs/src/components/ui/Card/CardContent.tsx new file mode 100644 index 0000000..5fcc868 --- /dev/null +++ b/apps/docs/src/components/ui/Card/CardContent.tsx @@ -0,0 +1,9 @@ +import { cn } from "@/lib/cn"; +import type { HTMLAttributes } from "react"; + +export type CardContentProps = HTMLAttributes; + +export const CardContent = ({ className, ...props }: CardContentProps) => ( +
+); +CardContent.displayName = "CardContent"; diff --git a/apps/docs/src/components/ui/Card/CardHeader.tsx b/apps/docs/src/components/ui/Card/CardHeader.tsx new file mode 100644 index 0000000..6f59f8b --- /dev/null +++ b/apps/docs/src/components/ui/Card/CardHeader.tsx @@ -0,0 +1,9 @@ +import { cn } from "@/lib/cn"; +import type { HTMLAttributes } from "react"; + +export type CardHeaderProps = HTMLAttributes; + +export const CardHeader = ({ className, ...props }: CardHeaderProps) => ( +
+); +CardHeader.displayName = "CardHeader"; diff --git a/apps/docs/src/components/ui/Card/index.ts b/apps/docs/src/components/ui/Card/index.ts index 24d3212..9eabd03 100644 --- a/apps/docs/src/components/ui/Card/index.ts +++ b/apps/docs/src/components/ui/Card/index.ts @@ -1 +1,3 @@ export * from "./Card"; +export * from "./CardContent"; +export * from "./CardHeader"; diff --git a/apps/docs/src/components/ui/DropdownMenu/DropdownMenu.tsx b/apps/docs/src/components/ui/DropdownMenu/DropdownMenu.tsx index 7cc4010..026e0a4 100644 --- a/apps/docs/src/components/ui/DropdownMenu/DropdownMenu.tsx +++ b/apps/docs/src/components/ui/DropdownMenu/DropdownMenu.tsx @@ -1,53 +1,3 @@ import { Menu } from "@base-ui/react/menu"; -import { cn } from "@/lib/utils"; export const DropdownMenu = Menu.Root; -export const DropdownMenuTrigger = Menu.Trigger; - -export type DropdownMenuContentProps = Menu.Popup.Props & - Pick; - -export const DropdownMenuContent = ({ - className, - sideOffset = 6, - ...props -}: DropdownMenuContentProps) => ( - - - - - -); - -export type DropdownMenuItemProps = Menu.Item.Props; - -export const DropdownMenuItem = ({ className, ...props }: DropdownMenuItemProps) => ( - -); - -export type DropdownMenuSeparatorProps = Menu.Separator.Props; - -export const DropdownMenuSeparator = ({ className, ...props }: DropdownMenuSeparatorProps) => ( - -); - -DropdownMenuContent.displayName = "DropdownMenuContent"; -DropdownMenuItem.displayName = "DropdownMenuItem"; -DropdownMenuSeparator.displayName = "DropdownMenuSeparator"; diff --git a/apps/docs/src/components/ui/DropdownMenu/DropdownMenuContent.tsx b/apps/docs/src/components/ui/DropdownMenu/DropdownMenuContent.tsx new file mode 100644 index 0000000..9ec1e27 --- /dev/null +++ b/apps/docs/src/components/ui/DropdownMenu/DropdownMenuContent.tsx @@ -0,0 +1,29 @@ +import { cn } from "@/lib/cn"; +import { Menu } from "@base-ui/react/menu"; + +export type DropdownMenuContentProps = Menu.Popup.Props & + Pick; + +export const DropdownMenuContent = ({ + className, + sideOffset = 6, + ...props +}: DropdownMenuContentProps) => ( + + + + + +); +DropdownMenuContent.displayName = "DropdownMenuContent"; diff --git a/apps/docs/src/components/ui/DropdownMenu/DropdownMenuItem.tsx b/apps/docs/src/components/ui/DropdownMenu/DropdownMenuItem.tsx new file mode 100644 index 0000000..66f8087 --- /dev/null +++ b/apps/docs/src/components/ui/DropdownMenu/DropdownMenuItem.tsx @@ -0,0 +1,15 @@ +import { cn } from "@/lib/cn"; +import { Menu } from "@base-ui/react/menu"; + +export type DropdownMenuItemProps = Menu.Item.Props; + +export const DropdownMenuItem = ({ className, ...props }: DropdownMenuItemProps) => ( + +); +DropdownMenuItem.displayName = "DropdownMenuItem"; diff --git a/apps/docs/src/components/ui/DropdownMenu/DropdownMenuSeparator.tsx b/apps/docs/src/components/ui/DropdownMenu/DropdownMenuSeparator.tsx new file mode 100644 index 0000000..759db2a --- /dev/null +++ b/apps/docs/src/components/ui/DropdownMenu/DropdownMenuSeparator.tsx @@ -0,0 +1,9 @@ +import { cn } from "@/lib/cn"; +import { Menu } from "@base-ui/react/menu"; + +export type DropdownMenuSeparatorProps = Menu.Separator.Props; + +export const DropdownMenuSeparator = ({ className, ...props }: DropdownMenuSeparatorProps) => ( + +); +DropdownMenuSeparator.displayName = "DropdownMenuSeparator"; diff --git a/apps/docs/src/components/ui/DropdownMenu/DropdownMenuTrigger.tsx b/apps/docs/src/components/ui/DropdownMenu/DropdownMenuTrigger.tsx new file mode 100644 index 0000000..6a8b7c6 --- /dev/null +++ b/apps/docs/src/components/ui/DropdownMenu/DropdownMenuTrigger.tsx @@ -0,0 +1,3 @@ +import { Menu } from "@base-ui/react/menu"; + +export const DropdownMenuTrigger = Menu.Trigger; diff --git a/apps/docs/src/components/ui/DropdownMenu/index.ts b/apps/docs/src/components/ui/DropdownMenu/index.ts index 54b11fc..1d1bb1f 100644 --- a/apps/docs/src/components/ui/DropdownMenu/index.ts +++ b/apps/docs/src/components/ui/DropdownMenu/index.ts @@ -1 +1,5 @@ export * from "./DropdownMenu"; +export * from "./DropdownMenuContent"; +export * from "./DropdownMenuItem"; +export * from "./DropdownMenuSeparator"; +export * from "./DropdownMenuTrigger"; diff --git a/apps/docs/src/content.ts b/apps/docs/src/docsEntries.ts similarity index 98% rename from apps/docs/src/content.ts rename to apps/docs/src/docsEntries.ts index a2b7ded..ec61678 100644 --- a/apps/docs/src/content.ts +++ b/apps/docs/src/docsEntries.ts @@ -112,5 +112,3 @@ export const docsEntries: DocsEntry[] = [ ], }, ]; - -export const getDocsEntry = (slug: string) => docsEntries.find((entry) => entry.slug === slug); diff --git a/apps/docs/src/getDocsEntry.ts b/apps/docs/src/getDocsEntry.ts new file mode 100644 index 0000000..d2c4117 --- /dev/null +++ b/apps/docs/src/getDocsEntry.ts @@ -0,0 +1,3 @@ +import { docsEntries } from "./docsEntries"; + +export const getDocsEntry = (slug: string) => docsEntries.find((entry) => entry.slug === slug); diff --git a/apps/docs/src/lib/PERSISTENT_DETECTION_OPTIONS.ts b/apps/docs/src/lib/PERSISTENT_DETECTION_OPTIONS.ts new file mode 100644 index 0000000..6207e04 --- /dev/null +++ b/apps/docs/src/lib/PERSISTENT_DETECTION_OPTIONS.ts @@ -0,0 +1,7 @@ +import type { DetectorOptions } from "i18next-browser-languagedetector"; + +export const PERSISTENT_DETECTION_OPTIONS: DetectorOptions = { + order: ["cookie", "localStorage"], + caches: ["cookie", "localStorage"], + lookupCookie: "i18next", +}; diff --git a/apps/docs/src/lib/THEME_PREPAINT_SCRIPT.ts b/apps/docs/src/lib/THEME_PREPAINT_SCRIPT.ts new file mode 100644 index 0000000..1a607b2 --- /dev/null +++ b/apps/docs/src/lib/THEME_PREPAINT_SCRIPT.ts @@ -0,0 +1,3 @@ +import { THEME_STORAGE_KEY } from "./THEME_STORAGE_KEY"; + +export const THEME_PREPAINT_SCRIPT = `(()=>{try{const value=window.localStorage.getItem("${THEME_STORAGE_KEY}");document.documentElement.dataset.theme=value==="dark"?"dark":"light"}catch{document.documentElement.dataset.theme="light"}})();`; diff --git a/apps/docs/src/lib/THEME_STORAGE_KEY.ts b/apps/docs/src/lib/THEME_STORAGE_KEY.ts new file mode 100644 index 0000000..c4b64c1 --- /dev/null +++ b/apps/docs/src/lib/THEME_STORAGE_KEY.ts @@ -0,0 +1 @@ +export const THEME_STORAGE_KEY = "anatomy-theme"; diff --git a/apps/docs/src/lib/applySavedLanguage.ts b/apps/docs/src/lib/applySavedLanguage.ts new file mode 100644 index 0000000..439dcc5 --- /dev/null +++ b/apps/docs/src/lib/applySavedLanguage.ts @@ -0,0 +1,14 @@ +import i18n from "./i18n"; +import { languageDetector } from "./languageDetector"; +import { PERSISTENT_DETECTION_OPTIONS } from "./PERSISTENT_DETECTION_OPTIONS"; +import { normalizeLanguage, type DocsLanguage } from "./normalizeLanguage"; +import { getSavedLanguage } from "./getSavedLanguage"; + +export const applySavedLanguage = async (): Promise => { + const language = getSavedLanguage() ?? "zh"; + languageDetector.init(i18n.services, PERSISTENT_DETECTION_OPTIONS); + if (normalizeLanguage(i18n.resolvedLanguage ?? i18n.language) !== language) { + await i18n.changeLanguage(language); + } + return language; +}; diff --git a/apps/docs/src/lib/applyTheme.ts b/apps/docs/src/lib/applyTheme.ts new file mode 100644 index 0000000..56f1eaa --- /dev/null +++ b/apps/docs/src/lib/applyTheme.ts @@ -0,0 +1,5 @@ +import { type DocsTheme } from "./getSavedTheme"; + +export const applyTheme = (theme: DocsTheme) => { + if (typeof document !== "undefined") document.documentElement.dataset.theme = theme; +}; diff --git a/apps/docs/src/lib/utils.ts b/apps/docs/src/lib/cn.ts similarity index 100% rename from apps/docs/src/lib/utils.ts rename to apps/docs/src/lib/cn.ts diff --git a/apps/docs/src/lib/getSavedLanguage.ts b/apps/docs/src/lib/getSavedLanguage.ts new file mode 100644 index 0000000..387d2c4 --- /dev/null +++ b/apps/docs/src/lib/getSavedLanguage.ts @@ -0,0 +1,14 @@ +import { Result } from "neverthrow"; +import { normalizeLanguage, type DocsLanguage } from "./normalizeLanguage"; + +export const getSavedLanguage = (): DocsLanguage | undefined => { + if (typeof document !== "undefined" && typeof document.cookie === "string") { + const match = document.cookie.match(/(?:^|; )i18next=([^;]+)/); + if (match?.[1]) { + const language = Result.fromThrowable(() => normalizeLanguage(decodeURIComponent(match[1]!)))().unwrapOr(undefined); + if (language) return language; + } + } + return typeof window === "undefined" ? undefined + : Result.fromThrowable(() => normalizeLanguage(window.localStorage.getItem("i18nextLng")))().unwrapOr(undefined); +}; diff --git a/apps/docs/src/lib/getSavedTheme.ts b/apps/docs/src/lib/getSavedTheme.ts new file mode 100644 index 0000000..a4de4fd --- /dev/null +++ b/apps/docs/src/lib/getSavedTheme.ts @@ -0,0 +1,12 @@ +import { THEME_STORAGE_KEY } from "./THEME_STORAGE_KEY"; +import { Result } from "neverthrow"; + +export type DocsTheme = "dark" | "light"; + +export const getSavedTheme = (): DocsTheme => { + if (typeof window === "undefined") return "light"; + + return Result.fromThrowable((): DocsTheme => + window.localStorage.getItem(THEME_STORAGE_KEY) === "dark" ? "dark" : "light", + )().unwrapOr("light"); +}; diff --git a/apps/docs/src/lib/i18n-server.ts b/apps/docs/src/lib/getServerLanguage.ts similarity index 86% rename from apps/docs/src/lib/i18n-server.ts rename to apps/docs/src/lib/getServerLanguage.ts index 1f3ab51..75ad33e 100644 --- a/apps/docs/src/lib/i18n-server.ts +++ b/apps/docs/src/lib/getServerLanguage.ts @@ -1,4 +1,4 @@ -export type DocsLanguage = "en" | "zh"; +import type { DocsLanguage } from "./normalizeLanguage"; const normalizeLanguage = (value: string | null | undefined): DocsLanguage => value?.toLowerCase().startsWith("en") ? "en" : "zh"; diff --git a/apps/docs/src/lib/i18n.ts b/apps/docs/src/lib/i18n.ts index fa5249e..3969fcd 100644 --- a/apps/docs/src/lib/i18n.ts +++ b/apps/docs/src/lib/i18n.ts @@ -1,49 +1,10 @@ import i18n from "i18next"; -import LanguageDetector, { type DetectorOptions } from "i18next-browser-languagedetector"; +import { languageDetector } from "./languageDetector"; +import { PERSISTENT_DETECTION_OPTIONS } from "./PERSISTENT_DETECTION_OPTIONS"; import { initReactI18next } from "react-i18next"; import en from "../locales/en.json"; import zh from "../locales/zh.json"; -export type DocsLanguage = "en" | "zh"; - -const PERSISTENT_DETECTION_OPTIONS: DetectorOptions = { - order: ["cookie", "localStorage"], - caches: ["cookie", "localStorage"], - lookupCookie: "i18next", -}; - -const normalizeLanguage = (value?: string | null): DocsLanguage | undefined => { - if (value?.toLowerCase().startsWith("en")) return "en"; - if (value?.toLowerCase().startsWith("zh")) return "zh"; - return undefined; -}; - -export const getSavedLanguage = (): DocsLanguage | undefined => { - if (typeof document !== "undefined" && typeof document.cookie === "string") { - const match = document.cookie.match(/(?:^|; )i18next=([^;]+)/); - if (match?.[1]) { - try { - const language = normalizeLanguage(decodeURIComponent(match[1])); - if (language) return language; - } catch { - // Ignore malformed preference cookies and fall back to local storage. - } - } - } - - if (typeof window !== "undefined") { - try { - return normalizeLanguage(window.localStorage.getItem("i18nextLng")); - } catch { - return undefined; - } - } - - return undefined; -}; - -const languageDetector = new LanguageDetector(); - i18n .use(languageDetector) .use(initReactI18next) @@ -65,16 +26,4 @@ i18n }, }); -export const applySavedLanguage = async (): Promise => { - const language = getSavedLanguage() ?? "zh"; - - languageDetector.init(i18n.services, PERSISTENT_DETECTION_OPTIONS); - - if (normalizeLanguage(i18n.resolvedLanguage ?? i18n.language) !== language) { - await i18n.changeLanguage(language); - } - - return language; -}; - export default i18n; diff --git a/apps/docs/src/lib/index.ts b/apps/docs/src/lib/index.ts new file mode 100644 index 0000000..a8c7547 --- /dev/null +++ b/apps/docs/src/lib/index.ts @@ -0,0 +1,12 @@ +export * from "./PERSISTENT_DETECTION_OPTIONS"; +export * from "./THEME_PREPAINT_SCRIPT"; +export * from "./THEME_STORAGE_KEY"; +export * from "./applySavedLanguage"; +export * from "./applyTheme"; +export * from "./cn"; +export * from "./getSavedLanguage"; +export * from "./getSavedTheme"; +export * from "./getServerLanguage"; +export * from "./languageDetector"; +export * from "./normalizeLanguage"; +export * from "./saveTheme"; diff --git a/apps/docs/src/lib/languageDetector.ts b/apps/docs/src/lib/languageDetector.ts new file mode 100644 index 0000000..1ca570b --- /dev/null +++ b/apps/docs/src/lib/languageDetector.ts @@ -0,0 +1,3 @@ +import LanguageDetector from "i18next-browser-languagedetector"; + +export const languageDetector = new LanguageDetector(); diff --git a/apps/docs/src/lib/normalizeLanguage.ts b/apps/docs/src/lib/normalizeLanguage.ts new file mode 100644 index 0000000..a33a095 --- /dev/null +++ b/apps/docs/src/lib/normalizeLanguage.ts @@ -0,0 +1,7 @@ +export type DocsLanguage = "en" | "zh"; + +export const normalizeLanguage = (value?: string | null): DocsLanguage | undefined => { + if (value?.toLowerCase().startsWith("en")) return "en"; + if (value?.toLowerCase().startsWith("zh")) return "zh"; + return undefined; +}; diff --git a/apps/docs/src/lib/saveTheme.ts b/apps/docs/src/lib/saveTheme.ts new file mode 100644 index 0000000..0bf98ab --- /dev/null +++ b/apps/docs/src/lib/saveTheme.ts @@ -0,0 +1,10 @@ +import { applyTheme } from "./applyTheme"; +import { type DocsTheme } from "./getSavedTheme"; +import { THEME_STORAGE_KEY } from "./THEME_STORAGE_KEY"; +import { Result } from "neverthrow"; + +export const saveTheme = (theme: DocsTheme) => { + applyTheme(theme); + + Result.fromThrowable(() => window.localStorage.setItem(THEME_STORAGE_KEY, theme))().unwrapOr(undefined); +}; diff --git a/apps/docs/src/lib/theme.ts b/apps/docs/src/lib/theme.ts deleted file mode 100644 index f938488..0000000 --- a/apps/docs/src/lib/theme.ts +++ /dev/null @@ -1,29 +0,0 @@ -export type DocsTheme = "dark" | "light"; - -export const THEME_STORAGE_KEY = "anatomy-theme"; - -export const THEME_PREPAINT_SCRIPT = `(()=>{try{const value=window.localStorage.getItem("${THEME_STORAGE_KEY}");document.documentElement.dataset.theme=value==="dark"?"dark":"light"}catch{document.documentElement.dataset.theme="light"}})();`; - -export const getSavedTheme = (): DocsTheme => { - if (typeof window === "undefined") return "light"; - - try { - return window.localStorage.getItem(THEME_STORAGE_KEY) === "dark" ? "dark" : "light"; - } catch { - return "light"; - } -}; - -export const applyTheme = (theme: DocsTheme) => { - if (typeof document !== "undefined") document.documentElement.dataset.theme = theme; -}; - -export const saveTheme = (theme: DocsTheme) => { - applyTheme(theme); - - try { - window.localStorage.setItem(THEME_STORAGE_KEY, theme); - } catch { - // The visual preference still applies when storage is unavailable. - } -}; diff --git a/apps/docs/src/pages/docs-page.tsx b/apps/docs/src/pages/DocsPage.tsx similarity index 98% rename from apps/docs/src/pages/docs-page.tsx rename to apps/docs/src/pages/DocsPage.tsx index 73542a1..0f2b950 100644 --- a/apps/docs/src/pages/docs-page.tsx +++ b/apps/docs/src/pages/DocsPage.tsx @@ -1,11 +1,12 @@ -import { ArrowLeft, ArrowRight, Clipboard, ExternalLink } from "lucide-react"; -import { Link, useParams } from "@tanstack/react-router"; -import { useTranslation } from "react-i18next"; +import { PublicLayout } from "@/components/PublicLayout"; import { Badge } from "@/components/ui/Badge"; import { Button } from "@/components/ui/Button"; import { Card } from "@/components/ui/Card"; -import { PublicLayout } from "@/components/PublicLayout"; -import { docsEntries, getDocsEntry } from "@/content"; +import { docsEntries } from "@/docsEntries"; +import { getDocsEntry } from "@/getDocsEntry"; +import { Link, useParams } from "@tanstack/react-router"; +import { ArrowLeft, ArrowRight, Clipboard, ExternalLink } from "lucide-react"; +import { useTranslation } from "react-i18next"; const groups = ["Guide", "Reference", "Concepts", "Development"] as const; const toRoute = (href: string) => href as never; diff --git a/apps/docs/src/pages/home.tsx b/apps/docs/src/pages/HomePage.tsx similarity index 100% rename from apps/docs/src/pages/home.tsx rename to apps/docs/src/pages/HomePage.tsx diff --git a/apps/docs/src/pages/index.ts b/apps/docs/src/pages/index.ts new file mode 100644 index 0000000..8f4c9ff --- /dev/null +++ b/apps/docs/src/pages/index.ts @@ -0,0 +1,2 @@ +export * from "./DocsPage"; +export * from "./HomePage"; diff --git a/apps/docs/src/routes/$.tsx b/apps/docs/src/routes/$.tsx index 9e372f4..c96aecb 100644 --- a/apps/docs/src/routes/$.tsx +++ b/apps/docs/src/routes/$.tsx @@ -1,4 +1,4 @@ import { createFileRoute } from "@tanstack/react-router"; -import { DocsPage } from "@/pages/docs-page"; +import { DocsPage } from "@/pages/DocsPage"; export const Route = createFileRoute("/$")({ component: DocsPage }); diff --git a/apps/docs/src/routes/-RootDocument.tsx b/apps/docs/src/routes/-RootDocument.tsx index 0bf2d11..ddb7124 100644 --- a/apps/docs/src/routes/-RootDocument.tsx +++ b/apps/docs/src/routes/-RootDocument.tsx @@ -1,9 +1,9 @@ +import { AppBootScreen } from "@/components/AppBootScreen/AppBootScreen"; +import "@/lib/i18n"; +import { THEME_PREPAINT_SCRIPT } from "@/lib/THEME_PREPAINT_SCRIPT"; import { HeadContent, Outlet, Scripts } from "@tanstack/react-router"; import { useEffect } from "react"; import { useTranslation } from "react-i18next"; -import { AppBootScreen } from "@/components/AppBootScreen/AppBootScreen"; -import "@/lib/i18n"; -import { THEME_PREPAINT_SCRIPT } from "@/lib/theme"; export const RootDocument = () => { const { i18n } = useTranslation(); diff --git a/apps/docs/src/routes/docs.$slug.tsx b/apps/docs/src/routes/docs.$slug.tsx index 9029b0c..74d667c 100644 --- a/apps/docs/src/routes/docs.$slug.tsx +++ b/apps/docs/src/routes/docs.$slug.tsx @@ -1,4 +1,4 @@ import { createFileRoute } from "@tanstack/react-router"; -import { DocsPage } from "@/pages/docs-page"; +import { DocsPage } from "@/pages/DocsPage"; export const Route = createFileRoute("/docs/$slug")({ component: DocsPage }); diff --git a/apps/docs/src/routes/index.tsx b/apps/docs/src/routes/index.tsx index 557d8c7..a0281cf 100644 --- a/apps/docs/src/routes/index.tsx +++ b/apps/docs/src/routes/index.tsx @@ -1,4 +1,4 @@ import { createFileRoute } from "@tanstack/react-router"; -import { HomePage } from "@/pages/home"; +import { HomePage } from "@/pages/HomePage"; export const Route = createFileRoute("/")({ component: HomePage }); diff --git a/apps/docs/vite.config.ts b/apps/docs/vite.config.ts index 439c44e..acd2d5b 100644 --- a/apps/docs/vite.config.ts +++ b/apps/docs/vite.config.ts @@ -1,13 +1,13 @@ import { withPayload } from "@payloadcms/tanstack-start"; +import tailwindcss from "@tailwindcss/vite"; import { tanstackStart } from "@tanstack/react-start/plugin/vite"; +import react from "@vitejs/plugin-react"; import rsc from "@vitejs/plugin-rsc"; import { nitro } from "nitro/vite"; -import react from "@vitejs/plugin-react"; -import tailwindcss from "@tailwindcss/vite"; import path from "node:path"; import { fileURLToPath } from "node:url"; import { defineConfig } from "vite"; -import { docsEntries } from "./src/content"; +import { docsEntries } from "./src/docsEntries"; const dirname = path.dirname(fileURLToPath(import.meta.url)); diff --git a/bun.lock b/bun.lock index 11dcc5b..36a551d 100644 --- a/bun.lock +++ b/bun.lock @@ -55,6 +55,7 @@ "i18next-browser-languagedetector": "^8.2.1", "lucide-react": "^1.7.0", "motion": "^13.2.0", + "neverthrow": "^8.2.0", "nitro": "3.0.260429-beta", "payload": "4.0.0-canary.29", "react": "19.2.8", diff --git a/package.json b/package.json index 6086c6e..c6e0423 100644 --- a/package.json +++ b/package.json @@ -40,7 +40,8 @@ "check-types": "bunx --no-install tsc --noEmit && bun run --filter '*' check-types", "lint": "bun run --filter '*' lint", "test": "bun run --filter '*' test", - "quality": "bun run check-types && bun run lint && bun run test && bun run build" + "quality": "bun run anatomy:check && bun run check-types && bun run lint && bun run test && bun run build", + "anatomy:check": "bun run anatomy . --git-files" }, "engines": { "bun": ">=1.3.0" diff --git a/packages/anatomy/src/core/AnatomyCheckCode.ts b/packages/anatomy/src/core/AnatomyCheckCode.ts new file mode 100644 index 0000000..3517adf --- /dev/null +++ b/packages/anatomy/src/core/AnatomyCheckCode.ts @@ -0,0 +1,14 @@ +export const AnatomyCheckCode = { + missingRequired: "missing_required", + unexpectedEntry: "unexpected_entry", + nameMismatch: "name_mismatch", + bindingFormatMismatch: "binding_format_mismatch", + bindingPatternMismatch: "binding_pattern_mismatch", + bindingConsistencyMismatch: "binding_consistency_mismatch", + nestingMismatch: "nesting_mismatch", + quantityExceeded: "quantity_exceeded", + oneOfMismatch: "one_of_mismatch", + exportCountMismatch: "export_count_mismatch", + exportNameMismatch: "export_name_mismatch", + exportKindMismatch: "export_kind_mismatch", +} as const; diff --git a/packages/anatomy/src/core/AnatomyQueryPathError.ts b/packages/anatomy/src/core/AnatomyQueryPathError.ts new file mode 100644 index 0000000..db52317 --- /dev/null +++ b/packages/anatomy/src/core/AnatomyQueryPathError.ts @@ -0,0 +1,6 @@ +export class AnatomyQueryPathError extends Error { + constructor(public readonly path: string) { + super(`Query path must be relative to the target, without parent traversal: ${path}`); + this.name = "AnatomyQueryPathError"; + } +} diff --git a/packages/anatomy/src/core/AnatomySourceAnalysisError.ts b/packages/anatomy/src/core/AnatomySourceAnalysisError.ts new file mode 100644 index 0000000..53629d6 --- /dev/null +++ b/packages/anatomy/src/core/AnatomySourceAnalysisError.ts @@ -0,0 +1,6 @@ +export class AnatomySourceAnalysisError extends Error { + constructor(public readonly path: string, message: string) { + super(message); + this.name = "AnatomySourceAnalysisError"; + } +} diff --git a/packages/anatomy/src/core/AnatomyValidationCode.ts b/packages/anatomy/src/core/AnatomyValidationCode.ts new file mode 100644 index 0000000..02c1154 --- /dev/null +++ b/packages/anatomy/src/core/AnatomyValidationCode.ts @@ -0,0 +1,13 @@ +export const AnatomyValidationCode = { + duplicateId: "duplicate_id", + duplicateLiteralName: "duplicate_literal_name", + invalidPlaceholder: "invalid_placeholder", + invalidBinding: "invalid_binding", + invalidBindingName: "invalid_binding_name", + invalidBindingFormat: "invalid_binding_format", + invalidBindingPattern: "invalid_binding_pattern", + absolutePath: "absolute_path", + invalidOneOfRange: "invalid_one_of_range", + impossibleOneOf: "impossible_one_of", + invalidExportName: "invalid_export_name", +} as const; diff --git a/packages/anatomy/src/core/anatomy-tree.spec.ts b/packages/anatomy/src/core/anatomy-tree.spec.ts index 503b647..6976edd 100644 --- a/packages/anatomy/src/core/anatomy-tree.spec.ts +++ b/packages/anatomy/src/core/anatomy-tree.spec.ts @@ -1,14 +1,12 @@ -import { describe, it, expect } from "vitest"; -import { - createEmptyStructure, - createDirectoryEntry, - createFileEntry, - insertAnatomyNode, - removeAnatomyNode, - updateAnatomyNode, - locateNodeInTree, - groupSiblingEntries, -} from "./anatomy-tree"; +import { describe, expect, it } from "vitest"; +import { createDirectoryEntry } from "./createDirectoryEntry"; +import { createEmptyStructure } from "./createEmptyStructure"; +import { createFileEntry } from "./createFileEntry"; +import { groupSiblingEntries } from "./groupSiblingEntries"; +import { insertAnatomyNode } from "./insertAnatomyNode"; +import { locateNodeInTree } from "./locateNodeInTree"; +import { removeAnatomyNode } from "./removeAnatomyNode"; +import { updateAnatomyNode } from "./updateAnatomyNode"; describe("anatomy-tree", () => { describe("createEmptyStructure", () => { diff --git a/packages/anatomy/src/core/anatomy-tree.ts b/packages/anatomy/src/core/anatomy-tree.ts deleted file mode 100644 index b282542..0000000 --- a/packages/anatomy/src/core/anatomy-tree.ts +++ /dev/null @@ -1,295 +0,0 @@ -import type { AnatomyNode, AnatomyEntry, AnatomyStructure, AnatomyQuantity } from "@anatomy-cli/schemas"; - -// ---- helpers ---- - -const uid = (() => { - const state = { counter: 0 }; - - return (): string => { - state.counter += 1; - - return crypto.randomUUID?.() ?? `node-${state.counter}-${Date.now()}`; - }; -})(); - -const cloneEntry = (entry: T): T => { - return JSON.parse(JSON.stringify(entry)) as T; -}; - -// ---- factory functions ---- - -export const createFileEntry = ( - name: string, - quantity?: AnatomyQuantity, -): AnatomyEntry & { kind: "file" } => { - return { - id: uid(), - kind: "file", - name: { type: "literal", value: name }, - quantity: quantity ?? "optional", - policyOverrides: {}, - }; -}; - -export const createDirectoryEntry = ( - name: string, - children: AnatomyNode[] = [], - quantity?: AnatomyQuantity, -): AnatomyEntry & { kind: "directory" } => { - return { - id: uid(), - kind: "directory", - name: { type: "literal", value: name }, - quantity: quantity ?? "optional", - policyOverrides: {}, - children, - }; -}; - -// ---- tree queries ---- - -type TreeNodeParent = - | (AnatomyEntry & { kind: "directory" }) - | Extract - | null; - -type TreeNodeResult = { found: true; parent: TreeNodeParent; index: number } | { found: false }; - -type LocatedNode = - | { found: true; node: AnatomyNode; parent: TreeNodeParent; index: number } - | { found: false }; - -export const locateNodeInTree = ( - children: AnatomyNode[], - nodeId: string, - parent: TreeNodeParent = null, -): LocatedNode => { - for (const [i, child] of children.entries()) { - if (child.id === nodeId) { - return { found: true, node: child, parent, index: i }; - } - - if (child.kind === "directory") { - const result = locateNodeInTree(child.children, nodeId, child); - if (result.found) return result; - } - - if (child.kind === "one_of") { - for (const [j, alt] of child.alternatives.entries()) { - if (alt.id === nodeId) { - return { found: true, node: alt, parent: child, index: j }; - } - - if (alt.kind === "directory") { - const result = locateNodeInTree(alt.children, nodeId, alt); - if (result.found) return result; - } - } - } - } - - return { found: false }; -}; - -export const findNodeInTree = ( - children: AnatomyNode[], - nodeId: string, - parent: (AnatomyEntry & { kind: "directory" }) | null = null, -): TreeNodeResult => { - const located = locateNodeInTree(children, nodeId, parent); - - if (!located.found) return { found: false }; - - return { - found: true, - parent: located.parent, - index: located.index, - }; -}; - -// ---- tree mutations (immutable) ---- - -export const insertAnatomyNode = ( - root: AnatomyStructure, - parentId: string | null, - node: AnatomyNode, -): AnatomyStructure => { - if (parentId === null) { - return { - ...root, - root: { ...root.root, children: [...root.root.children, node] }, - }; - } - - const located = locateNodeInTree(root.root.children, parentId); - if (!located.found) return root; - - const targetNode = located.node; - if (targetNode.kind !== "directory") return root; - - const updated = cloneEntry(targetNode); - updated.children = [...updated.children, node]; - - return replaceNodeInTree(root, targetNode.id, updated); -}; - -export const removeAnatomyNode = (root: AnatomyStructure, nodeId: string): AnatomyStructure => { - const located = locateNodeInTree(root.root.children, nodeId); - if (!located.found) return root; - - const { parent } = located; - - if (parent === null) { - // Root-level node - return { - ...root, - root: { - ...root.root, - children: root.root.children.filter((c) => c.id !== nodeId), - }, - }; - } - - if (parent.kind === "one_of") { - const updated: AnatomyNode = { - ...parent, - alternatives: parent.alternatives.filter((c) => c.id !== nodeId), - }; - - return replaceNodeInTree(root, parent.id, updated); - } - - const updated = cloneEntry(parent); - if (updated.kind !== "directory") return root; - updated.children = updated.children.filter((c) => c.id !== nodeId); - - return replaceNodeInTree(root, parent.id, updated); -}; - -export const updateAnatomyNode = ( - root: AnatomyStructure, - nodeId: string, - updater: (node: AnatomyNode) => AnatomyNode, -): AnatomyStructure => { - // Check root children - const rootIdx = root.root.children.findIndex((c) => c.id === nodeId); - if (rootIdx !== -1) { - const updated = root.root.children.map((c, i) => (i === rootIdx ? updater(c) : c)); - - return { ...root, root: { ...root.root, children: updated } }; - } - - // Recurse - const recurse = (children: AnatomyNode[]): AnatomyNode[] => { - return children.map((child) => { - if (child.id === nodeId) return updater(child); - - if (child.kind === "directory") { - return { ...child, children: recurse(child.children) }; - } - - if (child.kind === "one_of") { - return { - ...child, - alternatives: child.alternatives.map((alt) => { - if (alt.id === nodeId) { - const updated = updater(alt as AnatomyNode); - // Alternatives must remain entries (file or directory) - return updated.kind === "one_of" ? alt : (updated as AnatomyEntry); - } - - if (alt.kind === "directory") { - return { ...alt, children: recurse(alt.children) }; - } - - return alt; - }), - }; - } - - return child; - }); - }; - - return { - ...root, - root: { ...root.root, children: recurse(root.root.children) }, - }; -}; - -const replaceNodeInTree = ( - root: AnatomyStructure, - nodeId: string, - replacement: AnatomyNode, -): AnatomyStructure => { - return updateAnatomyNode(root, nodeId, () => replacement); -}; - -export const groupSiblingEntries = ( - root: AnatomyStructure, - parentId: string | null, - entryIds: string[], -): AnatomyStructure => { - const targetParent = - parentId === null - ? root.root - : (() => { - const located = locateNodeInTree(root.root.children, parentId); - - return located.found && located.node.kind === "directory" ? located.node : null; - })(); - - if (!targetParent) return root; - const children = targetParent.children; - - const entriesToGroup: AnatomyEntry[] = []; - const remaining: AnatomyNode[] = []; - - for (const child of children) { - if (entryIds.includes(child.id) && (child.kind === "file" || child.kind === "directory")) { - entriesToGroup.push(child as AnatomyEntry); - } else { - remaining.push(child); - } - } - - if (entriesToGroup.length < 2) return root; - - const group: AnatomyNode = { - id: uid(), - kind: "one_of", - minimumMatches: 1, - maximumMatches: 1, - alternatives: entriesToGroup.map((e) => cloneEntry(e)), - }; - - const newChildren = [...remaining, group]; - - if (parentId === null) { - return { ...root, root: { ...root.root, children: newChildren } }; - } - - const located = locateNodeInTree(root.root.children, parentId); - if (!located.found || located.node.kind !== "directory") return root; - - const updated = cloneEntry(located.node); - updated.children = newChildren; - - return replaceNodeInTree(root, located.node.id, updated); -}; - -// ---- default structure ---- - -export const createEmptyStructure = (): AnatomyStructure => { - return { - schemaVersion: 1, - defaultPolicies: { - missingRequired: "block", - unexpectedEntry: "warn", - nameMismatch: "warn", - nestingMismatch: "block", - }, - bindings: {}, - root: { children: [] }, - }; -}; diff --git a/packages/anatomy/src/core/anatomy-rule-paths.ts b/packages/anatomy/src/core/anatomyRulePaths.ts similarity index 100% rename from packages/anatomy/src/core/anatomy-rule-paths.ts rename to packages/anatomy/src/core/anatomyRulePaths.ts diff --git a/packages/anatomy/src/core/check-anatomy.spec.ts b/packages/anatomy/src/core/check-anatomy.spec.ts index 7bf9a8f..2524afb 100644 --- a/packages/anatomy/src/core/check-anatomy.spec.ts +++ b/packages/anatomy/src/core/check-anatomy.spec.ts @@ -1,12 +1,10 @@ import { type AnatomyDraftInput } from "@anatomy-cli/schemas"; -import { createEmptyAnatomyDraft } from "./createEmptyAnatomyDraft"; import { describe, expect, it } from "vitest"; -import { - AnatomyCheckCode, - checkAnatomy, - type AnatomyFileTreeEntry, -} from "./check-anatomy"; -import { AnatomyValidationCode } from "./validate-anatomy-for-publish"; +import { AnatomyCheckCode } from "./AnatomyCheckCode"; +import { AnatomyValidationCode } from "./AnatomyValidationCode"; +import { checkAnatomy } from "./checkAnatomy"; +import { createEmptyAnatomyDraft } from "./createEmptyAnatomyDraft"; +import { type AnatomyFileTreeEntry } from "./planAnatomyCheck"; const file = (id: string, name: string, quantity = "exactly_one" as const) => { return { diff --git a/packages/anatomy/src/core/checkAnatomy.ts b/packages/anatomy/src/core/checkAnatomy.ts new file mode 100644 index 0000000..dec3183 --- /dev/null +++ b/packages/anatomy/src/core/checkAnatomy.ts @@ -0,0 +1,44 @@ +import { +type AnatomyDraftInput, +type AnatomySourceExports +} from "@anatomy-cli/schemas"; +import { err, ok, type Result as ResultType } from "neverthrow"; +import { AnatomyCheckCode } from "./AnatomyCheckCode"; +import { AnatomySourceAnalysisError } from "./AnatomySourceAnalysisError"; +import { planAnatomyCheck, type AnatomyCheckIssue, type AnatomyCheckResult, type AnatomyFileTreeEntry } from "./planAnatomyCheck"; +import { type AnatomyValidationIssue } from "./validateAnatomyForPublish"; + +export const checkAnatomy = ( + definition: AnatomyDraftInput, + entries: AnatomyFileTreeEntry[], + sourceExports: ReadonlyMap = new Map(), +): ResultType => { + const plan = planAnatomyCheck(definition, entries); + if (plan.isErr()) return err(plan.error); + const { structuralResult, exportChecks } = plan.value; + for (const check of exportChecks) { + const actual = sourceExports.get(check.path); + if (actual === undefined) return err(new AnatomySourceAnalysisError(check.path, `Exports were not analyzed for ${check.path}`)); + const addIssue = (code: AnatomyCheckIssue["code"], message: string) => { + structuralResult.issues.push({ + code, message, severity: check.policy, path: check.path, constraintId: check.constraintId, + expectedExport: check.expectedName, actualExports: actual, + }); + structuralResult.summary[check.policy] += 1; + }; + if (actual.length !== 1) { + addIssue(AnatomyCheckCode.exportCountMismatch, + `Expected exactly one named function export "${check.expectedName}" but found ${actual.length} runtime exports`); + continue; + } + const exported = actual[0]!; + if (exported.name === "default" || exported.name !== check.expectedName) { + addIssue(AnatomyCheckCode.exportNameMismatch, `Expected named export "${check.expectedName}" but found "${exported.name}"`); + } + if (exported.kind !== "function") { + addIssue(AnatomyCheckCode.exportKindMismatch, `Expected function export "${check.expectedName}" but found a non-function value`); + } + } + structuralResult.conforms = structuralResult.summary.block === 0; + return ok(structuralResult); +}; diff --git a/packages/anatomy/src/core/cloneEntry.ts b/packages/anatomy/src/core/cloneEntry.ts new file mode 100644 index 0000000..2650f35 --- /dev/null +++ b/packages/anatomy/src/core/cloneEntry.ts @@ -0,0 +1,5 @@ +import type { AnatomyEntry } from "@anatomy-cli/schemas"; + +export const cloneEntry = (entry: T): T => { + return JSON.parse(JSON.stringify(entry)) as T; +}; diff --git a/packages/anatomy/src/core/createDirectoryEntry.ts b/packages/anatomy/src/core/createDirectoryEntry.ts new file mode 100644 index 0000000..d2e0329 --- /dev/null +++ b/packages/anatomy/src/core/createDirectoryEntry.ts @@ -0,0 +1,17 @@ +import type { AnatomyEntry, AnatomyNode, AnatomyQuantity } from "@anatomy-cli/schemas"; +import { uid } from "./uid"; + +export const createDirectoryEntry = ( + name: string, + children: AnatomyNode[] = [], + quantity?: AnatomyQuantity, +): AnatomyEntry & { kind: "directory" } => { + return { + id: uid(), + kind: "directory", + name: { type: "literal", value: name }, + quantity: quantity ?? "optional", + policyOverrides: {}, + children, + }; +}; diff --git a/packages/anatomy/src/core/createEmptyStructure.ts b/packages/anatomy/src/core/createEmptyStructure.ts new file mode 100644 index 0000000..c8c1b45 --- /dev/null +++ b/packages/anatomy/src/core/createEmptyStructure.ts @@ -0,0 +1,15 @@ +import type { AnatomyStructure } from "@anatomy-cli/schemas"; + +export const createEmptyStructure = (): AnatomyStructure => { + return { + schemaVersion: 1, + defaultPolicies: { + missingRequired: "block", + unexpectedEntry: "warn", + nameMismatch: "warn", + nestingMismatch: "block", + }, + bindings: {}, + root: { children: [] }, + }; +}; diff --git a/packages/anatomy/src/core/createFileEntry.ts b/packages/anatomy/src/core/createFileEntry.ts new file mode 100644 index 0000000..4b4d5e9 --- /dev/null +++ b/packages/anatomy/src/core/createFileEntry.ts @@ -0,0 +1,15 @@ +import type { AnatomyEntry, AnatomyQuantity } from "@anatomy-cli/schemas"; +import { uid } from "./uid"; + +export const createFileEntry = ( + name: string, + quantity?: AnatomyQuantity, +): AnatomyEntry & { kind: "file" } => { + return { + id: uid(), + kind: "file", + name: { type: "literal", value: name }, + quantity: quantity ?? "optional", + policyOverrides: {}, + }; +}; diff --git a/packages/anatomy/src/core/match-anatomy-name.ts b/packages/anatomy/src/core/evaluateName.ts similarity index 100% rename from packages/anatomy/src/core/match-anatomy-name.ts rename to packages/anatomy/src/core/evaluateName.ts diff --git a/packages/anatomy/src/core/findNodeInTree.ts b/packages/anatomy/src/core/findNodeInTree.ts new file mode 100644 index 0000000..ff1086b --- /dev/null +++ b/packages/anatomy/src/core/findNodeInTree.ts @@ -0,0 +1,20 @@ +import type { AnatomyEntry, AnatomyNode } from "@anatomy-cli/schemas"; +import { type TreeNodeParent, locateNodeInTree } from "./locateNodeInTree"; + +type TreeNodeResult = { found: true; parent: TreeNodeParent; index: number } | { found: false }; + +export const findNodeInTree = ( + children: AnatomyNode[], + nodeId: string, + parent: (AnatomyEntry & { kind: "directory" }) | null = null, +): TreeNodeResult => { + const located = locateNodeInTree(children, nodeId, parent); + + if (!located.found) return { found: false }; + + return { + found: true, + parent: located.parent, + index: located.index, + }; +}; diff --git a/packages/anatomy/src/core/function-export.spec.ts b/packages/anatomy/src/core/function-export.spec.ts index c7c1bec..6d03178 100644 --- a/packages/anatomy/src/core/function-export.spec.ts +++ b/packages/anatomy/src/core/function-export.spec.ts @@ -1,7 +1,8 @@ -import { describe, expect, it } from "vitest"; import { AnatomyDraftInputSchema, type AnatomySourceExports } from "@anatomy-cli/schemas"; -import { checkAnatomy, planAnatomyCheck } from "./check-anatomy"; -import { queryAnatomy } from "./query-anatomy"; +import { describe, expect, it } from "vitest"; +import { checkAnatomy } from "./checkAnatomy"; +import { planAnatomyCheck } from "./planAnatomyCheck"; +import { queryAnatomy } from "./queryAnatomy"; const definition = () => AnatomyDraftInputSchema.parse({ name: "Function files", purpose: "One named function per file", diff --git a/packages/anatomy/src/core/groupSiblingEntries.ts b/packages/anatomy/src/core/groupSiblingEntries.ts new file mode 100644 index 0000000..a4a3a02 --- /dev/null +++ b/packages/anatomy/src/core/groupSiblingEntries.ts @@ -0,0 +1,58 @@ +import type { AnatomyEntry, AnatomyNode, AnatomyStructure } from "@anatomy-cli/schemas"; +import { cloneEntry } from "./cloneEntry"; +import { locateNodeInTree } from "./locateNodeInTree"; +import { replaceNodeInTree } from "./replaceNodeInTree"; +import { uid } from "./uid"; + +export const groupSiblingEntries = ( + root: AnatomyStructure, + parentId: string | null, + entryIds: string[], +): AnatomyStructure => { + const targetParent = + parentId === null + ? root.root + : (() => { + const located = locateNodeInTree(root.root.children, parentId); + + return located.found && located.node.kind === "directory" ? located.node : null; + })(); + + if (!targetParent) return root; + const children = targetParent.children; + + const entriesToGroup: AnatomyEntry[] = []; + const remaining: AnatomyNode[] = []; + + for (const child of children) { + if (entryIds.includes(child.id) && (child.kind === "file" || child.kind === "directory")) { + entriesToGroup.push(child as AnatomyEntry); + } else { + remaining.push(child); + } + } + + if (entriesToGroup.length < 2) return root; + + const group: AnatomyNode = { + id: uid(), + kind: "one_of", + minimumMatches: 1, + maximumMatches: 1, + alternatives: entriesToGroup.map((e) => cloneEntry(e)), + }; + + const newChildren = [...remaining, group]; + + if (parentId === null) { + return { ...root, root: { ...root.root, children: newChildren } }; + } + + const located = locateNodeInTree(root.root.children, parentId); + if (!located.found || located.node.kind !== "directory") return root; + + const updated = cloneEntry(located.node); + updated.children = newChildren; + + return replaceNodeInTree(root, located.node.id, updated); +}; diff --git a/packages/anatomy/src/core/index.ts b/packages/anatomy/src/core/index.ts index 6434ed6..8a4ce43 100644 --- a/packages/anatomy/src/core/index.ts +++ b/packages/anatomy/src/core/index.ts @@ -1,10 +1,23 @@ -export * from "./anatomy-tree"; -export * from "./check-anatomy"; +export * from "./resolveAnatomyExportName"; +export * from "./anatomyRulePaths"; +export * from "./AnatomyCheckCode"; +export * from "./AnatomyQueryPathError"; +export * from "./AnatomySourceAnalysisError"; +export * from "./AnatomyValidationCode"; +export * from "./checkAnatomy"; +export * from "./createDirectoryEntry"; export * from "./createEmptyAnatomyDraft"; +export * from "./createEmptyStructure"; +export * from "./createFileEntry"; +export * from "./findNodeInTree"; +export * from "./groupSiblingEntries"; +export * from "./insertAnatomyNode"; +export * from "./locateNodeInTree"; +export * from "./evaluateName"; +export * from "./planAnatomyCheck"; +export * from "./queryAnatomy"; +export * from "./removeAnatomyNode"; export * from "./resolveAnatomyPolicies"; export * from "./ResolvedAnatomyPolicy"; -export * from "./validate-anatomy-for-publish"; -export * from "./anatomy-rule-paths"; -export * from "./query-anatomy"; -export * from "./match-anatomy-name"; -export * from "./anatomy-export-name"; +export * from "./updateAnatomyNode"; +export * from "./validateAnatomyForPublish"; diff --git a/packages/anatomy/src/core/insertAnatomyNode.ts b/packages/anatomy/src/core/insertAnatomyNode.ts new file mode 100644 index 0000000..548b569 --- /dev/null +++ b/packages/anatomy/src/core/insertAnatomyNode.ts @@ -0,0 +1,28 @@ +import type { AnatomyNode, AnatomyStructure } from "@anatomy-cli/schemas"; +import { cloneEntry } from "./cloneEntry"; +import { locateNodeInTree } from "./locateNodeInTree"; +import { replaceNodeInTree } from "./replaceNodeInTree"; + +export const insertAnatomyNode = ( + root: AnatomyStructure, + parentId: string | null, + node: AnatomyNode, +): AnatomyStructure => { + if (parentId === null) { + return { + ...root, + root: { ...root.root, children: [...root.root.children, node] }, + }; + } + + const located = locateNodeInTree(root.root.children, parentId); + if (!located.found) return root; + + const targetNode = located.node; + if (targetNode.kind !== "directory") return root; + + const updated = cloneEntry(targetNode); + updated.children = [...updated.children, node]; + + return replaceNodeInTree(root, targetNode.id, updated); +}; diff --git a/packages/anatomy/src/core/locateNodeInTree.ts b/packages/anatomy/src/core/locateNodeInTree.ts new file mode 100644 index 0000000..440bd01 --- /dev/null +++ b/packages/anatomy/src/core/locateNodeInTree.ts @@ -0,0 +1,42 @@ +import type { AnatomyEntry, AnatomyNode } from "@anatomy-cli/schemas"; + +export type TreeNodeParent = + | (AnatomyEntry & { kind: "directory" }) + | Extract + | null; + +type LocatedNode = + | { found: true; node: AnatomyNode; parent: TreeNodeParent; index: number } + | { found: false }; + +export const locateNodeInTree = ( + children: AnatomyNode[], + nodeId: string, + parent: TreeNodeParent = null, +): LocatedNode => { + for (const [i, child] of children.entries()) { + if (child.id === nodeId) { + return { found: true, node: child, parent, index: i }; + } + + if (child.kind === "directory") { + const result = locateNodeInTree(child.children, nodeId, child); + if (result.found) return result; + } + + if (child.kind === "one_of") { + for (const [j, alt] of child.alternatives.entries()) { + if (alt.id === nodeId) { + return { found: true, node: alt, parent: child, index: j }; + } + + if (alt.kind === "directory") { + const result = locateNodeInTree(alt.children, nodeId, alt); + if (result.found) return result; + } + } + } + } + + return { found: false }; +}; diff --git a/packages/anatomy/src/core/check-anatomy.ts b/packages/anatomy/src/core/planAnatomyCheck.ts similarity index 79% rename from packages/anatomy/src/core/check-anatomy.ts rename to packages/anatomy/src/core/planAnatomyCheck.ts index 9f0670c..d265b8a 100644 --- a/packages/anatomy/src/core/check-anatomy.ts +++ b/packages/anatomy/src/core/planAnatomyCheck.ts @@ -1,40 +1,23 @@ -import { evaluateName, type BindingScope, type NameMatch } from "./match-anatomy-name"; -import { err, ok, type Result as ResultType } from "neverthrow"; import { - type AnatomyDraftInput, - type AnatomyEntry, - type AnatomyNode, - type AnatomyPolicies, - type AnatomyPolicyOverrides, - type AnatomyFunctionExportCheck, - type AnatomySourceExports, +type AnatomyDraftInput, +type AnatomyEntry, +type AnatomyFunctionExportCheck, +type AnatomyNode, +type AnatomyPolicies, +type AnatomyPolicyOverrides, +type AnatomySourceExports, } from "@anatomy-cli/schemas"; -import { resolveAnatomyExportName } from "./anatomy-export-name"; +import { err, ok, type Result as ResultType } from "neverthrow"; +import { resolveAnatomyExportName } from "./resolveAnatomyExportName"; +import { AnatomyCheckCode } from "./AnatomyCheckCode"; +import { evaluateName, type BindingScope, type NameMatch } from "./evaluateName"; import { resolveAnatomyPolicies } from "./resolveAnatomyPolicies"; -import { - validateAnatomyForPublish, - type AnatomyValidationIssue, -} from "./validate-anatomy-for-publish"; +import { validateAnatomyForPublish, type AnatomyValidationIssue } from "./validateAnatomyForPublish"; export type AnatomyFileTreeEntry = | { kind: "file"; name: string } | { kind: "directory"; name: string; children: AnatomyFileTreeEntry[] }; -export const AnatomyCheckCode = { - missingRequired: "missing_required", - unexpectedEntry: "unexpected_entry", - nameMismatch: "name_mismatch", - bindingFormatMismatch: "binding_format_mismatch", - bindingPatternMismatch: "binding_pattern_mismatch", - bindingConsistencyMismatch: "binding_consistency_mismatch", - nestingMismatch: "nesting_mismatch", - quantityExceeded: "quantity_exceeded", - oneOfMismatch: "one_of_mismatch", - exportCountMismatch: "export_count_mismatch", - exportNameMismatch: "export_name_mismatch", - exportKindMismatch: "export_kind_mismatch", -} as const; - export type AnatomyCheckIssue = { code: (typeof AnatomyCheckCode)[keyof typeof AnatomyCheckCode]; severity: AnatomyPolicies[keyof AnatomyPolicies]; @@ -56,6 +39,7 @@ export type AnatomyCheckResult = { }; type PolicyAncestor = { id: string; overrides: AnatomyPolicyOverrides }; + type NameMatchCandidate = { index: number; match: Exclude; @@ -347,45 +331,3 @@ export const planAnatomyCheck = ( return ok({ structuralResult: { issues, summary, conforms: summary.block === 0 }, exportChecks }); }; - -export class AnatomySourceAnalysisError extends Error { - constructor(public readonly path: string, message: string) { - super(message); - this.name = "AnatomySourceAnalysisError"; - } -} - -export const checkAnatomy = ( - definition: AnatomyDraftInput, - entries: AnatomyFileTreeEntry[], - sourceExports: ReadonlyMap = new Map(), -): ResultType => { - const plan = planAnatomyCheck(definition, entries); - if (plan.isErr()) return err(plan.error); - const { structuralResult, exportChecks } = plan.value; - for (const check of exportChecks) { - const actual = sourceExports.get(check.path); - if (actual === undefined) return err(new AnatomySourceAnalysisError(check.path, `Exports were not analyzed for ${check.path}`)); - const addIssue = (code: AnatomyCheckIssue["code"], message: string) => { - structuralResult.issues.push({ - code, message, severity: check.policy, path: check.path, constraintId: check.constraintId, - expectedExport: check.expectedName, actualExports: actual, - }); - structuralResult.summary[check.policy] += 1; - }; - if (actual.length !== 1) { - addIssue(AnatomyCheckCode.exportCountMismatch, - `Expected exactly one named function export "${check.expectedName}" but found ${actual.length} runtime exports`); - continue; - } - const exported = actual[0]!; - if (exported.name === "default" || exported.name !== check.expectedName) { - addIssue(AnatomyCheckCode.exportNameMismatch, `Expected named export "${check.expectedName}" but found "${exported.name}"`); - } - if (exported.kind !== "function") { - addIssue(AnatomyCheckCode.exportKindMismatch, `Expected function export "${check.expectedName}" but found a non-function value`); - } - } - structuralResult.conforms = structuralResult.summary.block === 0; - return ok(structuralResult); -}; diff --git a/packages/anatomy/src/core/query-anatomy.spec.ts b/packages/anatomy/src/core/query-anatomy.spec.ts index 99c6962..76f2188 100644 --- a/packages/anatomy/src/core/query-anatomy.spec.ts +++ b/packages/anatomy/src/core/query-anatomy.spec.ts @@ -1,8 +1,8 @@ import { AnatomyDraftInputSchema, AnatomyQueryWithConstraintsSchema } from "@anatomy-cli/schemas"; import { describe, expect, it } from "vitest"; -import { checkAnatomy } from "./check-anatomy"; -import { queryAnatomy } from "./query-anatomy"; -import { anatomyRulePaths } from "./anatomy-rule-paths"; +import { anatomyRulePaths } from "./anatomyRulePaths"; +import { checkAnatomy } from "./checkAnatomy"; +import { queryAnatomy } from "./queryAnatomy"; const serviceDefinition = () => AnatomyDraftInputSchema.parse({ name: "Services", purpose: "Agent workflow", diff --git a/packages/anatomy/src/core/query-anatomy.ts b/packages/anatomy/src/core/queryAnatomy.ts similarity index 92% rename from packages/anatomy/src/core/query-anatomy.ts rename to packages/anatomy/src/core/queryAnatomy.ts index dba09dc..628df83 100644 --- a/packages/anatomy/src/core/query-anatomy.ts +++ b/packages/anatomy/src/core/queryAnatomy.ts @@ -1,20 +1,14 @@ -import { err, ok, type Result } from "neverthrow"; import { AnatomyQueryWithConstraintsSchema, type AnatomyDraftInput, type AnatomyNode, type AnatomyQueryWithConstraints } from "@anatomy-cli/schemas"; -import { evaluateName } from "./match-anatomy-name"; +import { err, ok, type Result } from "neverthrow"; +import { resolveAnatomyExportName } from "./resolveAnatomyExportName"; +import { anatomyRulePaths } from "./anatomyRulePaths"; +import { AnatomyQueryPathError } from "./AnatomyQueryPathError"; +import { evaluateName } from "./evaluateName"; import { resolveAnatomyPolicies } from "./resolveAnatomyPolicies"; -import { anatomyRulePaths } from "./anatomy-rule-paths"; -import { resolveAnatomyExportName } from "./anatomy-export-name"; -import { validateAnatomyForPublish, type AnatomyValidationIssue } from "./validate-anatomy-for-publish"; +import { validateAnatomyForPublish, type AnatomyValidationIssue } from "./validateAnatomyForPublish"; const QueryStatus = AnatomyQueryWithConstraintsSchema.shape.status.enum; -export class AnatomyQueryPathError extends Error { - constructor(public readonly path: string) { - super(`Query path must be relative to the target, without parent traversal: ${path}`); - this.name = "AnatomyQueryPathError"; - } -} - export const queryAnatomy = ( definition: AnatomyDraftInput, path: string, diff --git a/packages/anatomy/src/core/removeAnatomyNode.ts b/packages/anatomy/src/core/removeAnatomyNode.ts new file mode 100644 index 0000000..7405916 --- /dev/null +++ b/packages/anatomy/src/core/removeAnatomyNode.ts @@ -0,0 +1,37 @@ +import type { AnatomyNode, AnatomyStructure } from "@anatomy-cli/schemas"; +import { cloneEntry } from "./cloneEntry"; +import { locateNodeInTree } from "./locateNodeInTree"; +import { replaceNodeInTree } from "./replaceNodeInTree"; + +export const removeAnatomyNode = (root: AnatomyStructure, nodeId: string): AnatomyStructure => { + const located = locateNodeInTree(root.root.children, nodeId); + if (!located.found) return root; + + const { parent } = located; + + if (parent === null) { + // Root-level node + return { + ...root, + root: { + ...root.root, + children: root.root.children.filter((c) => c.id !== nodeId), + }, + }; + } + + if (parent.kind === "one_of") { + const updated: AnatomyNode = { + ...parent, + alternatives: parent.alternatives.filter((c) => c.id !== nodeId), + }; + + return replaceNodeInTree(root, parent.id, updated); + } + + const updated = cloneEntry(parent); + if (updated.kind !== "directory") return root; + updated.children = updated.children.filter((c) => c.id !== nodeId); + + return replaceNodeInTree(root, parent.id, updated); +}; diff --git a/packages/anatomy/src/core/replaceNodeInTree.ts b/packages/anatomy/src/core/replaceNodeInTree.ts new file mode 100644 index 0000000..a9d4031 --- /dev/null +++ b/packages/anatomy/src/core/replaceNodeInTree.ts @@ -0,0 +1,10 @@ +import type { AnatomyNode, AnatomyStructure } from "@anatomy-cli/schemas"; +import { updateAnatomyNode } from "./updateAnatomyNode"; + +export const replaceNodeInTree = ( + root: AnatomyStructure, + nodeId: string, + replacement: AnatomyNode, +): AnatomyStructure => { + return updateAnatomyNode(root, nodeId, () => replacement); +}; diff --git a/packages/anatomy/src/core/anatomy-export-name.ts b/packages/anatomy/src/core/resolveAnatomyExportName.ts similarity index 100% rename from packages/anatomy/src/core/anatomy-export-name.ts rename to packages/anatomy/src/core/resolveAnatomyExportName.ts diff --git a/packages/anatomy/src/core/uid.ts b/packages/anatomy/src/core/uid.ts new file mode 100644 index 0000000..7159430 --- /dev/null +++ b/packages/anatomy/src/core/uid.ts @@ -0,0 +1,6 @@ +const state = { counter: 0 }; + +export const uid = (): string => { + state.counter += 1; + return crypto.randomUUID?.() ?? `node-${state.counter}-${Date.now()}`; +}; diff --git a/packages/anatomy/src/core/updateAnatomyNode.ts b/packages/anatomy/src/core/updateAnatomyNode.ts new file mode 100644 index 0000000..e9af3d7 --- /dev/null +++ b/packages/anatomy/src/core/updateAnatomyNode.ts @@ -0,0 +1,52 @@ +import type { AnatomyEntry, AnatomyNode, AnatomyStructure } from "@anatomy-cli/schemas"; + +export const updateAnatomyNode = ( + root: AnatomyStructure, + nodeId: string, + updater: (node: AnatomyNode) => AnatomyNode, +): AnatomyStructure => { + // Check root children + const rootIdx = root.root.children.findIndex((c) => c.id === nodeId); + if (rootIdx !== -1) { + const updated = root.root.children.map((c, i) => (i === rootIdx ? updater(c) : c)); + + return { ...root, root: { ...root.root, children: updated } }; + } + + // Recurse + const recurse = (children: AnatomyNode[]): AnatomyNode[] => { + return children.map((child) => { + if (child.id === nodeId) return updater(child); + + if (child.kind === "directory") { + return { ...child, children: recurse(child.children) }; + } + + if (child.kind === "one_of") { + return { + ...child, + alternatives: child.alternatives.map((alt) => { + if (alt.id === nodeId) { + const updated = updater(alt as AnatomyNode); + // Alternatives must remain entries (file or directory) + return updated.kind === "one_of" ? alt : (updated as AnatomyEntry); + } + + if (alt.kind === "directory") { + return { ...alt, children: recurse(alt.children) }; + } + + return alt; + }), + }; + } + + return child; + }); + }; + + return { + ...root, + root: { ...root.root, children: recurse(root.root.children) }, + }; +}; diff --git a/packages/anatomy/src/core/validate-anatomy-for-publish.ts b/packages/anatomy/src/core/validateAnatomyForPublish.ts similarity index 93% rename from packages/anatomy/src/core/validate-anatomy-for-publish.ts rename to packages/anatomy/src/core/validateAnatomyForPublish.ts index fe86318..7539c9a 100644 --- a/packages/anatomy/src/core/validate-anatomy-for-publish.ts +++ b/packages/anatomy/src/core/validateAnatomyForPublish.ts @@ -1,19 +1,6 @@ -import { err, ok, Result, type Result as ResultType } from "neverthrow"; import type { AnatomyDraftInput, AnatomyEntry, AnatomyNode } from "@anatomy-cli/schemas"; - -export const AnatomyValidationCode = { - duplicateId: "duplicate_id", - duplicateLiteralName: "duplicate_literal_name", - invalidPlaceholder: "invalid_placeholder", - invalidBinding: "invalid_binding", - invalidBindingName: "invalid_binding_name", - invalidBindingFormat: "invalid_binding_format", - invalidBindingPattern: "invalid_binding_pattern", - absolutePath: "absolute_path", - invalidOneOfRange: "invalid_one_of_range", - impossibleOneOf: "impossible_one_of", - invalidExportName: "invalid_export_name", -} as const; +import { err, ok, Result, type Result as ResultType } from "neverthrow"; +import { AnatomyValidationCode } from "./AnatomyValidationCode"; export type AnatomyValidationIssue = { code: (typeof AnatomyValidationCode)[keyof typeof AnatomyValidationCode]; @@ -24,7 +11,9 @@ export type AnatomyValidationIssue = { }; const PlaceholderPattern = /^[^<>/\\]*<[^<>/\\]+>[^<>/\\]*$/; + const BindingNamePattern = /^[A-Za-z][A-Za-z0-9_]*$/; + const SupportedBindingFormats = new Set([ "PascalCase", "camelCase", @@ -32,11 +21,14 @@ const SupportedBindingFormats = new Set([ "snake_case", "SCREAMING_SNAKE_CASE", ]); + const compilePattern = Result.fromThrowable( (pattern: string) => new RegExp(`^(?:${pattern})$`), () => undefined, ); + const WindowsDrivePattern = /^[a-zA-Z]:[\\/]/; + const UncPathPattern = /^\\\\/; const isRealPathExpression = (value: string): boolean => { diff --git a/packages/schemas/anatomy.json b/packages/schemas/anatomy.json new file mode 100644 index 0000000..a8878b3 --- /dev/null +++ b/packages/schemas/anatomy.json @@ -0,0 +1,206 @@ +{ + "name": "Anatomy schemas package", + "purpose": "Focused copy of the repository contract for schemas; tests prevent divergence.", + "structure": { + "schemaVersion": 1, + "defaultPolicies": { + "missingRequired": "block", + "unexpectedEntry": "block", + "nameMismatch": "block", + "nestingMismatch": "block" + }, + "root": { + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "anatomy.json" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "package.json" }, + "quantity": "exactly_one" + }, + { + "kind": "directory", + "name": { "type": "literal", "value": "src" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "directory", + "name": { "type": "literal", "value": "anatomy" }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyBindingFormatSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyBindingSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyCheckWithDiagnosticsSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyContract.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyDetailSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyDirectoryEntrySchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyDraftCreateInputSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyDraftInput.spec.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyDraftInputSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyDraftSaveInputSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyDraftSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyEntrySchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyFileEntrySchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyFunctionExportCheckSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyFunctionExportRuleSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyListInputSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyNameExpressionSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyNodeSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyOneOfGroupSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyPoliciesSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyPolicyOverridesSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyPolicyValueSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyPublishedVersionListInputSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyQuantitySchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyQueryWithConstraintsSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomySourceExportsSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyStatusSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyStructureSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomySummarySchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "AnatomyVersionSchema.ts" }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { "type": "literal", "value": "index.ts" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "file", + "name": { "type": "literal", "value": "index.ts" }, + "quantity": "exactly_one" + } + ] + }, + { + "kind": "file", + "name": { "type": "literal", "value": "tsconfig.json" }, + "quantity": "exactly_one" + } + ] + } + } +} diff --git a/packages/schemas/src/anatomy/AnatomyBindingFormat.schema.ts b/packages/schemas/src/anatomy/AnatomyBindingFormatSchema.ts similarity index 100% rename from packages/schemas/src/anatomy/AnatomyBindingFormat.schema.ts rename to packages/schemas/src/anatomy/AnatomyBindingFormatSchema.ts diff --git a/packages/schemas/src/anatomy/AnatomyBinding.schema.ts b/packages/schemas/src/anatomy/AnatomyBindingSchema.ts similarity index 98% rename from packages/schemas/src/anatomy/AnatomyBinding.schema.ts rename to packages/schemas/src/anatomy/AnatomyBindingSchema.ts index ee09c1c..88452dd 100644 --- a/packages/schemas/src/anatomy/AnatomyBinding.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyBindingSchema.ts @@ -1,7 +1,7 @@ import { Result } from "neverthrow"; import { z } from "zod/v4"; -import { AnatomyBindingFormatSchema } from "./AnatomyBindingFormat.schema"; +import { AnatomyBindingFormatSchema } from "./AnatomyBindingFormatSchema"; const compilePattern = Result.fromThrowable( (pattern: string) => new RegExp(`^(?:${pattern})$`), diff --git a/packages/schemas/src/anatomy/AnatomyCheckWithDiagnosticsSchema.ts b/packages/schemas/src/anatomy/AnatomyCheckWithDiagnosticsSchema.ts index 412f719..f4656d7 100644 --- a/packages/schemas/src/anatomy/AnatomyCheckWithDiagnosticsSchema.ts +++ b/packages/schemas/src/anatomy/AnatomyCheckWithDiagnosticsSchema.ts @@ -1,6 +1,6 @@ import { z } from "zod/v4"; -import { AnatomyNodeSchema } from "./AnatomyNode.schema"; -import { AnatomyPolicyValueSchema } from "./AnatomyPolicyValue.schema"; +import { AnatomyNodeSchema } from "./AnatomyNodeSchema"; +import { AnatomyPolicyValueSchema } from "./AnatomyPolicyValueSchema"; import { AnatomySourceExportsSchema } from "./AnatomySourceExportsSchema"; export const AnatomyCheckWithDiagnosticsSchema = z.object({ @@ -23,6 +23,7 @@ export const AnatomyCheckWithDiagnosticsSchema = z.object({ definition: z.object({ path: z.string(), name: z.string(), schemaVersion: z.literal(1) }), targetPath: z.string(), ignoredNames: z.array(z.string()), + fileSelection: z.enum(["filesystem", "git"]).optional(), }); export type AnatomyCheckWithDiagnostics = z.infer; diff --git a/packages/schemas/src/anatomy/AnatomyContract.spec.ts b/packages/schemas/src/anatomy/AnatomyContract.spec.ts index 47f800a..07aacfb 100644 --- a/packages/schemas/src/anatomy/AnatomyContract.spec.ts +++ b/packages/schemas/src/anatomy/AnatomyContract.spec.ts @@ -1,5 +1,5 @@ import { describe, expect, it } from "vitest"; -import { AnatomyDraftInputSchema } from "./AnatomyDraftInput.schema"; +import { AnatomyDraftInputSchema } from "./AnatomyDraftInputSchema"; const definition = () => ({ name: "Contract", purpose: "Reject unsupported rules", diff --git a/packages/schemas/src/anatomy/AnatomyDetail.schema.ts b/packages/schemas/src/anatomy/AnatomyDetailSchema.ts similarity index 86% rename from packages/schemas/src/anatomy/AnatomyDetail.schema.ts rename to packages/schemas/src/anatomy/AnatomyDetailSchema.ts index b64e629..c7b3a93 100644 --- a/packages/schemas/src/anatomy/AnatomyDetail.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyDetailSchema.ts @@ -1,7 +1,7 @@ import { z } from "zod/v4"; -import { AnatomyDraftSchema } from "./AnatomyDraft.schema"; -import { AnatomyVersionSchema } from "./AnatomyVersion.schema"; +import { AnatomyDraftSchema } from "./AnatomyDraftSchema"; +import { AnatomyVersionSchema } from "./AnatomyVersionSchema"; /** Complete Anatomy aggregate view, including its draft, version history, and usage. */ export const AnatomyDetailSchema = z.object({ diff --git a/packages/schemas/src/anatomy/AnatomyDirectoryEntry.schema.ts b/packages/schemas/src/anatomy/AnatomyDirectoryEntrySchema.ts similarity index 95% rename from packages/schemas/src/anatomy/AnatomyDirectoryEntry.schema.ts rename to packages/schemas/src/anatomy/AnatomyDirectoryEntrySchema.ts index febbc31..f52189a 100644 --- a/packages/schemas/src/anatomy/AnatomyDirectoryEntry.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyDirectoryEntrySchema.ts @@ -1,7 +1,7 @@ import { z } from "zod/v4"; -import { AnatomyFileEntrySchema, type AnatomyFileEntry } from "./AnatomyFileEntry.schema"; -import { AnatomyNodeSchema, type AnatomyNode } from "./AnatomyNode.schema"; +import { AnatomyFileEntrySchema, type AnatomyFileEntry } from "./AnatomyFileEntrySchema"; +import { AnatomyNodeSchema, type AnatomyNode } from "./AnatomyNodeSchema"; /** Directory node and its recursive children in an Anatomy tree. */ export const AnatomyDirectoryEntrySchema: z.ZodType< diff --git a/packages/schemas/src/anatomy/AnatomyDraftCreateInput.schema.ts b/packages/schemas/src/anatomy/AnatomyDraftCreateInputSchema.ts similarity index 79% rename from packages/schemas/src/anatomy/AnatomyDraftCreateInput.schema.ts rename to packages/schemas/src/anatomy/AnatomyDraftCreateInputSchema.ts index 832c7f4..d63fc8d 100644 --- a/packages/schemas/src/anatomy/AnatomyDraftCreateInput.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyDraftCreateInputSchema.ts @@ -1,5 +1,5 @@ import { z } from "zod/v4"; -import { AnatomyDraftInputSchema } from "./AnatomyDraftInput.schema"; +import { AnatomyDraftInputSchema } from "./AnatomyDraftInputSchema"; export const AnatomyDraftCreateInputSchema = AnatomyDraftInputSchema.extend({ id: z.string().uuid().optional(), diff --git a/packages/schemas/src/anatomy/AnatomyDraftInput.spec.ts b/packages/schemas/src/anatomy/AnatomyDraftInput.spec.ts index 724a289..260840e 100644 --- a/packages/schemas/src/anatomy/AnatomyDraftInput.spec.ts +++ b/packages/schemas/src/anatomy/AnatomyDraftInput.spec.ts @@ -1,5 +1,5 @@ import { describe, expect, it } from "vitest"; -import { AnatomyDraftInputSchema } from "./AnatomyDraftInput.schema"; +import { AnatomyDraftInputSchema } from "./AnatomyDraftInputSchema"; const defaultPolicies = { missingRequired: "block" as const, diff --git a/packages/schemas/src/anatomy/AnatomyDraftInput.schema.ts b/packages/schemas/src/anatomy/AnatomyDraftInputSchema.ts similarity index 89% rename from packages/schemas/src/anatomy/AnatomyDraftInput.schema.ts rename to packages/schemas/src/anatomy/AnatomyDraftInputSchema.ts index 1b591cb..f826447 100644 --- a/packages/schemas/src/anatomy/AnatomyDraftInput.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyDraftInputSchema.ts @@ -1,6 +1,6 @@ import { z } from "zod/v4"; -import { AnatomyStructureSchema } from "./AnatomyStructure.schema"; +import { AnatomyStructureSchema } from "./AnatomyStructureSchema"; /** Author-managed definition used to create or replace an Anatomy draft. */ export const AnatomyDraftInputSchema = z.strictObject({ diff --git a/packages/schemas/src/anatomy/AnatomyDraftSaveInput.schema.ts b/packages/schemas/src/anatomy/AnatomyDraftSaveInputSchema.ts similarity index 83% rename from packages/schemas/src/anatomy/AnatomyDraftSaveInput.schema.ts rename to packages/schemas/src/anatomy/AnatomyDraftSaveInputSchema.ts index bdd9d10..36ade5a 100644 --- a/packages/schemas/src/anatomy/AnatomyDraftSaveInput.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyDraftSaveInputSchema.ts @@ -1,6 +1,6 @@ import { z } from "zod/v4"; -import { AnatomyDraftInputSchema } from "./AnatomyDraftInput.schema"; +import { AnatomyDraftInputSchema } from "./AnatomyDraftInputSchema"; /** Input contract for saving an Anatomy draft. */ export const AnatomyDraftSaveInputSchema = AnatomyDraftInputSchema.extend({ diff --git a/packages/schemas/src/anatomy/AnatomyDraft.schema.ts b/packages/schemas/src/anatomy/AnatomyDraftSchema.ts similarity index 91% rename from packages/schemas/src/anatomy/AnatomyDraft.schema.ts rename to packages/schemas/src/anatomy/AnatomyDraftSchema.ts index 1ad2ce0..b9d8e05 100644 --- a/packages/schemas/src/anatomy/AnatomyDraft.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyDraftSchema.ts @@ -1,6 +1,6 @@ import { z } from "zod/v4"; -import { AnatomyDraftInputSchema } from "./AnatomyDraftInput.schema"; +import { AnatomyDraftInputSchema } from "./AnatomyDraftInputSchema"; /** Editable working draft of an Anatomy before publication. */ export const AnatomyDraftSchema = AnatomyDraftInputSchema.extend({ diff --git a/packages/schemas/src/anatomy/AnatomyEntry.schema.ts b/packages/schemas/src/anatomy/AnatomyEntrySchema.ts similarity index 88% rename from packages/schemas/src/anatomy/AnatomyEntry.schema.ts rename to packages/schemas/src/anatomy/AnatomyEntrySchema.ts index cb09903..0300cb8 100644 --- a/packages/schemas/src/anatomy/AnatomyEntry.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyEntrySchema.ts @@ -3,8 +3,8 @@ import { z } from "zod/v4"; import { AnatomyDirectoryEntrySchema, type AnatomyDirectoryEntry, -} from "./AnatomyDirectoryEntry.schema"; -import { AnatomyFileEntrySchema, type AnatomyFileEntry } from "./AnatomyFileEntry.schema"; +} from "./AnatomyDirectoryEntrySchema"; +import { AnatomyFileEntrySchema, type AnatomyFileEntry } from "./AnatomyFileEntrySchema"; type AnatomyEntryValue = AnatomyFileEntry | AnatomyDirectoryEntry; diff --git a/packages/schemas/src/anatomy/AnatomyFileEntry.schema.ts b/packages/schemas/src/anatomy/AnatomyFileEntrySchema.ts similarity index 91% rename from packages/schemas/src/anatomy/AnatomyFileEntry.schema.ts rename to packages/schemas/src/anatomy/AnatomyFileEntrySchema.ts index a8b6735..77829a1 100644 --- a/packages/schemas/src/anatomy/AnatomyFileEntry.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyFileEntrySchema.ts @@ -1,8 +1,8 @@ import { z } from "zod/v4"; -import { AnatomyNameExpressionSchema } from "./AnatomyNameExpression.schema"; -import { AnatomyPolicyOverridesSchema } from "./AnatomyPolicyOverrides.schema"; -import { AnatomyQuantitySchema } from "./AnatomyQuantity.schema"; +import { AnatomyNameExpressionSchema } from "./AnatomyNameExpressionSchema"; +import { AnatomyPolicyOverridesSchema } from "./AnatomyPolicyOverridesSchema"; +import { AnatomyQuantitySchema } from "./AnatomyQuantitySchema"; import { AnatomyFunctionExportRuleSchema } from "./AnatomyFunctionExportRuleSchema"; /** File requirement with naming, quantity, and policy constraints. */ diff --git a/packages/schemas/src/anatomy/AnatomyFunctionExportCheckSchema.ts b/packages/schemas/src/anatomy/AnatomyFunctionExportCheckSchema.ts index 66f2dc9..ee0ac3e 100644 --- a/packages/schemas/src/anatomy/AnatomyFunctionExportCheckSchema.ts +++ b/packages/schemas/src/anatomy/AnatomyFunctionExportCheckSchema.ts @@ -1,5 +1,5 @@ import { z } from "zod/v4"; -import { AnatomyPolicyValueSchema } from "./AnatomyPolicyValue.schema"; +import { AnatomyPolicyValueSchema } from "./AnatomyPolicyValueSchema"; export const AnatomyFunctionExportCheckSchema = z.strictObject({ path: z.string(), diff --git a/packages/schemas/src/anatomy/AnatomyFunctionExportRuleSchema.ts b/packages/schemas/src/anatomy/AnatomyFunctionExportRuleSchema.ts index e0d18fe..09cf84e 100644 --- a/packages/schemas/src/anatomy/AnatomyFunctionExportRuleSchema.ts +++ b/packages/schemas/src/anatomy/AnatomyFunctionExportRuleSchema.ts @@ -1,6 +1,6 @@ import { z } from "zod/v4"; -import { AnatomyNameExpressionSchema } from "./AnatomyNameExpression.schema"; -import { AnatomyPolicyValueSchema } from "./AnatomyPolicyValue.schema"; +import { AnatomyNameExpressionSchema } from "./AnatomyNameExpressionSchema"; +import { AnatomyPolicyValueSchema } from "./AnatomyPolicyValueSchema"; export const AnatomyFunctionExportRuleSchema = z.strictObject({ name: z.union([z.literal("file_stem"), AnatomyNameExpressionSchema]), diff --git a/packages/schemas/src/anatomy/AnatomyListInput.schema.ts b/packages/schemas/src/anatomy/AnatomyListInputSchema.ts similarity index 90% rename from packages/schemas/src/anatomy/AnatomyListInput.schema.ts rename to packages/schemas/src/anatomy/AnatomyListInputSchema.ts index f951943..9b92d59 100644 --- a/packages/schemas/src/anatomy/AnatomyListInput.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyListInputSchema.ts @@ -1,6 +1,6 @@ import { z } from "zod/v4"; -import { AnatomyStatusSchema } from "./AnatomyStatus.schema"; +import { AnatomyStatusSchema } from "./AnatomyStatusSchema"; /** Input contract for paginated Anatomy list queries. */ export const AnatomyListInputSchema = z.object({ diff --git a/packages/schemas/src/anatomy/AnatomyNameExpression.schema.ts b/packages/schemas/src/anatomy/AnatomyNameExpressionSchema.ts similarity index 100% rename from packages/schemas/src/anatomy/AnatomyNameExpression.schema.ts rename to packages/schemas/src/anatomy/AnatomyNameExpressionSchema.ts diff --git a/packages/schemas/src/anatomy/AnatomyNode.schema.ts b/packages/schemas/src/anatomy/AnatomyNodeSchema.ts similarity index 91% rename from packages/schemas/src/anatomy/AnatomyNode.schema.ts rename to packages/schemas/src/anatomy/AnatomyNodeSchema.ts index 83c44ea..706904a 100644 --- a/packages/schemas/src/anatomy/AnatomyNode.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyNodeSchema.ts @@ -1,7 +1,7 @@ import { z } from "zod/v4"; -import { AnatomyEntrySchema, type AnatomyEntry } from "./AnatomyEntry.schema"; -import { AnatomyOneOfGroupSchema, type AnatomyOneOfGroup } from "./AnatomyOneOfGroup.schema"; +import { AnatomyEntrySchema, type AnatomyEntry } from "./AnatomyEntrySchema"; +import { AnatomyOneOfGroupSchema, type AnatomyOneOfGroup } from "./AnatomyOneOfGroupSchema"; /** Any node permitted in an Anatomy tree, including entries and one-of groups. */ export const AnatomyNodeSchema: z.ZodType = z.lazy(() => diff --git a/packages/schemas/src/anatomy/AnatomyOneOfGroup.schema.ts b/packages/schemas/src/anatomy/AnatomyOneOfGroupSchema.ts similarity index 98% rename from packages/schemas/src/anatomy/AnatomyOneOfGroup.schema.ts rename to packages/schemas/src/anatomy/AnatomyOneOfGroupSchema.ts index cdd26e3..2c0f8d8 100644 --- a/packages/schemas/src/anatomy/AnatomyOneOfGroup.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyOneOfGroupSchema.ts @@ -1,6 +1,6 @@ import { z } from "zod/v4"; -import { AnatomyEntrySchema, type AnatomyEntry } from "./AnatomyEntry.schema"; +import { AnatomyEntrySchema, type AnatomyEntry } from "./AnatomyEntrySchema"; /** One-of group requiring a match count across multiple candidate entries. */ export const AnatomyOneOfGroupSchema: z.ZodType<{ diff --git a/packages/schemas/src/anatomy/AnatomyPolicy.schema.ts b/packages/schemas/src/anatomy/AnatomyPoliciesSchema.ts similarity index 90% rename from packages/schemas/src/anatomy/AnatomyPolicy.schema.ts rename to packages/schemas/src/anatomy/AnatomyPoliciesSchema.ts index 027f4e4..91049d3 100644 --- a/packages/schemas/src/anatomy/AnatomyPolicy.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyPoliciesSchema.ts @@ -1,5 +1,5 @@ import { z } from "zod/v4"; -import { AnatomyPolicyValueSchema } from "./AnatomyPolicyValue.schema"; +import { AnatomyPolicyValueSchema } from "./AnatomyPolicyValueSchema"; /** Default policies applied when a Crate does not conform to an Anatomy. */ export const AnatomyPoliciesSchema = z.strictObject({ diff --git a/packages/schemas/src/anatomy/AnatomyPolicyOverrides.schema.ts b/packages/schemas/src/anatomy/AnatomyPolicyOverridesSchema.ts similarity index 100% rename from packages/schemas/src/anatomy/AnatomyPolicyOverrides.schema.ts rename to packages/schemas/src/anatomy/AnatomyPolicyOverridesSchema.ts diff --git a/packages/schemas/src/anatomy/AnatomyPolicyValue.schema.ts b/packages/schemas/src/anatomy/AnatomyPolicyValueSchema.ts similarity index 100% rename from packages/schemas/src/anatomy/AnatomyPolicyValue.schema.ts rename to packages/schemas/src/anatomy/AnatomyPolicyValueSchema.ts diff --git a/packages/schemas/src/anatomy/AnatomyPublishedVersionListInput.schema.ts b/packages/schemas/src/anatomy/AnatomyPublishedVersionListInputSchema.ts similarity index 100% rename from packages/schemas/src/anatomy/AnatomyPublishedVersionListInput.schema.ts rename to packages/schemas/src/anatomy/AnatomyPublishedVersionListInputSchema.ts diff --git a/packages/schemas/src/anatomy/AnatomyQuantity.schema.ts b/packages/schemas/src/anatomy/AnatomyQuantitySchema.ts similarity index 100% rename from packages/schemas/src/anatomy/AnatomyQuantity.schema.ts rename to packages/schemas/src/anatomy/AnatomyQuantitySchema.ts diff --git a/packages/schemas/src/anatomy/AnatomyQueryWithConstraintsSchema.ts b/packages/schemas/src/anatomy/AnatomyQueryWithConstraintsSchema.ts index b9bbee4..adb7aaf 100644 --- a/packages/schemas/src/anatomy/AnatomyQueryWithConstraintsSchema.ts +++ b/packages/schemas/src/anatomy/AnatomyQueryWithConstraintsSchema.ts @@ -1,8 +1,8 @@ import { z } from "zod/v4"; -import { AnatomyNodeSchema } from "./AnatomyNode.schema"; -import { AnatomyPoliciesSchema } from "./AnatomyPolicy.schema"; -import { AnatomyBindingSchema } from "./AnatomyBinding.schema"; -import { AnatomyQuantitySchema } from "./AnatomyQuantity.schema"; +import { AnatomyNodeSchema } from "./AnatomyNodeSchema"; +import { AnatomyPoliciesSchema } from "./AnatomyPoliciesSchema"; +import { AnatomyBindingSchema } from "./AnatomyBindingSchema"; +import { AnatomyQuantitySchema } from "./AnatomyQuantitySchema"; export const AnatomyQueryWithConstraintsSchema = z.object({ contractVersion: z.literal(1), diff --git a/packages/schemas/src/anatomy/AnatomyStatus.schema.ts b/packages/schemas/src/anatomy/AnatomyStatusSchema.ts similarity index 100% rename from packages/schemas/src/anatomy/AnatomyStatus.schema.ts rename to packages/schemas/src/anatomy/AnatomyStatusSchema.ts diff --git a/packages/schemas/src/anatomy/AnatomyStructure.schema.ts b/packages/schemas/src/anatomy/AnatomyStructureSchema.ts similarity index 83% rename from packages/schemas/src/anatomy/AnatomyStructure.schema.ts rename to packages/schemas/src/anatomy/AnatomyStructureSchema.ts index eb41afe..14bfafb 100644 --- a/packages/schemas/src/anatomy/AnatomyStructure.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyStructureSchema.ts @@ -1,8 +1,8 @@ import { z } from "zod/v4"; -import { AnatomyPoliciesSchema } from "./AnatomyPolicy.schema"; -import { AnatomyNodeSchema } from "./AnatomyNode.schema"; -import { AnatomyBindingSchema } from "./AnatomyBinding.schema"; +import { AnatomyPoliciesSchema } from "./AnatomyPoliciesSchema"; +import { AnatomyNodeSchema } from "./AnatomyNodeSchema"; +import { AnatomyBindingSchema } from "./AnatomyBindingSchema"; /** Recursive filesystem structure contract that an Anatomy must satisfy. */ export const AnatomyStructureSchema = z.strictObject({ diff --git a/packages/schemas/src/anatomy/AnatomySummary.schema.ts b/packages/schemas/src/anatomy/AnatomySummarySchema.ts similarity index 100% rename from packages/schemas/src/anatomy/AnatomySummary.schema.ts rename to packages/schemas/src/anatomy/AnatomySummarySchema.ts diff --git a/packages/schemas/src/anatomy/AnatomyVersion.schema.ts b/packages/schemas/src/anatomy/AnatomyVersionSchema.ts similarity index 90% rename from packages/schemas/src/anatomy/AnatomyVersion.schema.ts rename to packages/schemas/src/anatomy/AnatomyVersionSchema.ts index b867448..dfaa971 100644 --- a/packages/schemas/src/anatomy/AnatomyVersion.schema.ts +++ b/packages/schemas/src/anatomy/AnatomyVersionSchema.ts @@ -1,6 +1,6 @@ import { z } from "zod/v4"; -import { AnatomyDraftInputSchema } from "./AnatomyDraftInput.schema"; +import { AnatomyDraftInputSchema } from "./AnatomyDraftInputSchema"; /** Immutable historical snapshot of a published Anatomy definition. */ export const AnatomyVersionSchema = AnatomyDraftInputSchema.extend({ diff --git a/packages/schemas/src/anatomy/index.ts b/packages/schemas/src/anatomy/index.ts index 8549862..8f17d53 100644 --- a/packages/schemas/src/anatomy/index.ts +++ b/packages/schemas/src/anatomy/index.ts @@ -1,26 +1,26 @@ -export * from "./AnatomyDetail.schema"; -export * from "./AnatomyBinding.schema"; -export * from "./AnatomyBindingFormat.schema"; -export * from "./AnatomyDirectoryEntry.schema"; -export * from "./AnatomyDraft.schema"; -export * from "./AnatomyDraftCreateInput.schema"; -export * from "./AnatomyDraftInput.schema"; -export * from "./AnatomyDraftSaveInput.schema"; -export * from "./AnatomyFileEntry.schema"; -export * from "./AnatomyEntry.schema"; -export * from "./AnatomyListInput.schema"; -export * from "./AnatomyNameExpression.schema"; -export * from "./AnatomyNode.schema"; -export * from "./AnatomyOneOfGroup.schema"; -export * from "./AnatomyPolicyOverrides.schema"; -export * from "./AnatomyPublishedVersionListInput.schema"; -export * from "./AnatomyPolicy.schema"; -export * from "./AnatomyPolicyValue.schema"; -export * from "./AnatomyQuantity.schema"; -export * from "./AnatomyStatus.schema"; -export * from "./AnatomyStructure.schema"; -export * from "./AnatomySummary.schema"; -export * from "./AnatomyVersion.schema"; +export * from "./AnatomyDetailSchema"; +export * from "./AnatomyBindingSchema"; +export * from "./AnatomyBindingFormatSchema"; +export * from "./AnatomyDirectoryEntrySchema"; +export * from "./AnatomyDraftSchema"; +export * from "./AnatomyDraftCreateInputSchema"; +export * from "./AnatomyDraftInputSchema"; +export * from "./AnatomyDraftSaveInputSchema"; +export * from "./AnatomyFileEntrySchema"; +export * from "./AnatomyEntrySchema"; +export * from "./AnatomyListInputSchema"; +export * from "./AnatomyNameExpressionSchema"; +export * from "./AnatomyNodeSchema"; +export * from "./AnatomyOneOfGroupSchema"; +export * from "./AnatomyPolicyOverridesSchema"; +export * from "./AnatomyPublishedVersionListInputSchema"; +export * from "./AnatomyPoliciesSchema"; +export * from "./AnatomyPolicyValueSchema"; +export * from "./AnatomyQuantitySchema"; +export * from "./AnatomyStatusSchema"; +export * from "./AnatomyStructureSchema"; +export * from "./AnatomySummarySchema"; +export * from "./AnatomyVersionSchema"; export * from "./AnatomyQueryWithConstraintsSchema"; export * from "./AnatomyCheckWithDiagnosticsSchema"; export * from "./AnatomyFunctionExportRuleSchema"; From 8cabc5534e100eb5be93d8c25b9f48fd1dbb15ce Mon Sep 17 00:00:00 2001 From: Zander Zhang <276678881@qq.com> Date: Tue, 15 Sep 2026 16:17:41 +0800 Subject: [PATCH 4/8] feat!: add portable Anatomy compositions and Node 24 SDK --- .github/workflows/ci.yml | 2 +- .github/workflows/deploy-docs.yml | 4 +- .nvmrc | 1 + README.md | 113 ++- README.zh-CN.md | 65 +- anatomy.coverage.json | 145 +++- anatomy.json | 342 ++++++++- .../anatomies/cli-source.anatomy.json | 20 +- .../anatomies/db-schema.bundle.json | 238 +++++++ .../drizzle-table-files.anatomy.json | 2 +- .../anatomies/service-files.anatomy.json | 2 +- apps/anatomy-cli/package.json | 18 +- apps/anatomy-cli/src/AnatomyCliUsage.ts | 1 + apps/anatomy-cli/src/DefaultIgnoredNames.ts | 2 +- apps/anatomy-cli/src/agent-workflow.spec.ts | 12 +- .../src/analyze-source-exports.spec.ts | 14 +- apps/anatomy-cli/src/analyzeSourceExports.ts | 164 +---- apps/anatomy-cli/src/cli-arguments.spec.ts | 12 +- apps/anatomy-cli/src/cli.spec.ts | 8 +- apps/anatomy-cli/src/collectFileTree.ts | 4 +- apps/anatomy-cli/src/collectGitFileTree.ts | 2 +- apps/anatomy-cli/src/collectSourceExports.ts | 2 +- apps/anatomy-cli/src/configurePath.ts | 6 +- apps/anatomy-cli/src/filesystem.spec.ts | 6 +- apps/anatomy-cli/src/findAnatomyDefinition.ts | 4 +- .../src/format-agent-result.spec.ts | 6 +- apps/anatomy-cli/src/formatAgentCheck.ts | 6 +- apps/anatomy-cli/src/formatAgentError.ts | 2 +- apps/anatomy-cli/src/formatAgentQuery.ts | 2 +- .../src/function-export-workflow.spec.ts | 14 +- apps/anatomy-cli/src/getPathPlan.ts | 2 +- apps/anatomy-cli/src/git-files.spec.ts | 8 +- apps/anatomy-cli/src/index.ts | 43 +- apps/anatomy-cli/src/install-main.ts | 6 +- apps/anatomy-cli/src/install.spec.ts | 18 +- apps/anatomy-cli/src/installUsage.ts | 2 +- apps/anatomy-cli/src/main.ts | 8 +- apps/anatomy-cli/src/packed-consumer.spec.ts | 297 ++++++++ apps/anatomy-cli/src/parseCliArguments.ts | 59 +- apps/anatomy-cli/src/parseInstallOptions.ts | 2 +- apps/anatomy-cli/src/readAnatomyDefinition.ts | 2 +- .../src/repository-contract.spec.ts | 6 +- apps/anatomy-cli/src/runAnatomyBundleCli.ts | 126 ++++ apps/anatomy-cli/src/runAnatomyCli.ts | 108 ++- apps/anatomy-cli/src/runInstallation.ts | 14 +- apps/anatomy-cli/src/source-contract.spec.ts | 6 +- apps/anatomy-cli/tsconfig.build.json | 18 + apps/anatomy-cli/tsconfig.json | 9 +- apps/docs/package.json | 3 + .../2026-09-01-placeholder-binding-design.md | 6 +- apps/docs/src/docsEntries.ts | 2 +- apps/docs/src/locales/en.json | 2 +- apps/docs/src/locales/zh.json | 2 +- bun.lock | 11 +- package.json | 9 +- packages/anatomy-cli-config/package.json | 3 + .../anatomy-cli-config/src/anatomies.spec.ts | 4 +- .../src/anatomies/dao.anatomy.json | 2 +- .../anatomies/drizzle-relation.anatomy.json | 2 +- .../src/anatomies/drizzle-table.anatomy.json | 2 +- .../src/anatomies/mobile-screen.anatomy.json | 2 +- .../src/anatomies/repository.anatomy.json | 2 +- .../src/anatomies/schemas.anatomy.json | 2 +- .../src/anatomies/service.anatomy.json | 2 +- .../src/anatomies/trpc-router.anatomy.json | 2 +- .../src/anatomies/zod-schema.anatomy.json | 2 +- packages/anatomy/package.json | 37 +- .../src/composition/AnatomyResourceLimits.ts | 9 + .../src/composition/checkInputBudget.ts | 43 ++ .../composition/compileAnatomyDefinition.ts | 105 +++ .../src/composition/composition.spec.ts | 667 ++++++++++++++++++ .../src/composition/createAnatomyFinding.ts | 79 +++ packages/anatomy/src/composition/index.ts | 5 + .../src/composition/planAnatomyBundle.ts | 295 ++++++++ .../src/composition/queryAnatomyBundle.ts | 235 ++++++ .../src/composition/resolveAnatomyBundle.ts | 223 ++++++ .../anatomy/src/composition/scanAnatomy.ts | 102 +++ .../src/composition/validateAnatomyBundle.ts | 10 + .../anatomy/src/core/anatomy-tree.spec.ts | 18 +- .../src/core/applyAnatomyExportChecks.ts | 62 ++ .../anatomy/src/core/check-anatomy.spec.ts | 10 +- packages/anatomy/src/core/checkAnatomy.ts | 53 +- .../anatomy/src/core/createDirectoryEntry.ts | 2 +- .../src/core/createEmptyAnatomyDraft.ts | 2 +- .../anatomy/src/core/createEmptyStructure.ts | 2 +- packages/anatomy/src/core/createFileEntry.ts | 2 +- packages/anatomy/src/core/findNodeInTree.ts | 2 +- .../anatomy/src/core/function-export.spec.ts | 8 +- .../anatomy/src/core/groupSiblingEntries.ts | 8 +- packages/anatomy/src/core/index.ts | 46 +- .../anatomy/src/core/insertAnatomyNode.ts | 6 +- packages/anatomy/src/core/planAnatomyCheck.ts | 217 ++++-- .../anatomy/src/core/query-anatomy.spec.ts | 8 +- packages/anatomy/src/core/queryAnatomy.ts | 173 +++-- .../anatomy/src/core/removeAnatomyNode.ts | 6 +- .../anatomy/src/core/replaceNodeInTree.ts | 2 +- .../src/core/resolveAnatomyPolicies.ts | 2 +- packages/anatomy/src/core/uid.ts | 8 +- .../src/core/validateAnatomyForPublish.ts | 2 +- packages/anatomy/src/index.ts | 3 +- .../src/source/analyzeSourceExports.ts | 296 ++++++++ packages/anatomy/src/source/index.ts | 1 + packages/anatomy/tsconfig.build.json | 17 + packages/anatomy/tsconfig.json | 9 +- packages/schemas/anatomy.json | 140 +++- packages/schemas/package.json | 33 +- .../src/anatomy/AnatomyBindingSchema.ts | 2 +- .../AnatomyCheckWithDiagnosticsSchema.ts | 9 +- .../src/anatomy/AnatomyContract.spec.ts | 14 +- .../src/anatomy/AnatomyDetailSchema.ts | 7 +- .../anatomy/AnatomyDirectoryEntrySchema.ts | 4 +- .../anatomy/AnatomyDraftCreateInputSchema.ts | 2 +- .../src/anatomy/AnatomyDraftInput.spec.ts | 10 +- .../src/anatomy/AnatomyDraftInputSchema.ts | 2 +- .../anatomy/AnatomyDraftSaveInputSchema.ts | 2 +- .../schemas/src/anatomy/AnatomyDraftSchema.ts | 4 +- .../schemas/src/anatomy/AnatomyEntrySchema.ts | 4 +- .../src/anatomy/AnatomyFileEntrySchema.ts | 11 +- .../AnatomyFunctionExportCheckSchema.ts | 2 +- .../AnatomyFunctionExportRuleSchema.ts | 4 +- .../src/anatomy/AnatomyListInputSchema.ts | 2 +- .../schemas/src/anatomy/AnatomyNodeSchema.ts | 4 +- .../src/anatomy/AnatomyOneOfGroupSchema.ts | 5 +- .../src/anatomy/AnatomyPoliciesSchema.ts | 2 +- .../AnatomyPublishedVersionListInputSchema.ts | 17 - .../AnatomyQueryWithConstraintsSchema.ts | 9 +- .../src/anatomy/AnatomyStructureSchema.ts | 10 +- .../src/anatomy/AnatomySummarySchema.ts | 2 - .../src/anatomy/AnatomyVersionSchema.ts | 19 - .../src/anatomy/createAnatomyNodeId.ts | 1 + packages/schemas/src/anatomy/index.ts | 55 +- .../AnatomyBundleQueryOutcomeSchema.ts | 32 + .../AnatomyBundleQueryRequestSchema.ts | 10 + .../src/composition/AnatomyBundleSchema.ts | 14 + .../AnatomyBundleValidationOutcomeSchema.ts | 16 + .../AnatomyCompositionNodeSchema.ts | 14 + .../composition/AnatomyDefinitionSchema.ts | 29 + .../composition/AnatomyDiagnosticSchema.ts | 23 + .../src/composition/AnatomyFindingSchema.ts | 21 + .../src/composition/AnatomyMountSchema.ts | 9 + .../src/composition/AnatomyOriginSchema.ts | 8 + .../src/composition/AnatomyRuleSchema.ts | 20 + .../composition/AnatomyScanOutcomeSchema.ts | 23 + .../composition/AnatomyScanRequestSchema.ts | 16 + .../src/composition/AnatomyTargetSchema.ts | 15 + packages/schemas/src/composition/index.ts | 14 + packages/schemas/src/index.ts | 3 +- packages/schemas/tsconfig.build.json | 17 + packages/schemas/tsconfig.json | 9 +- tsconfig.json | 27 +- vitest.config.ts | 49 ++ 151 files changed, 4807 insertions(+), 726 deletions(-) create mode 100644 .nvmrc create mode 100644 apps/anatomy-cli/anatomies/db-schema.bundle.json create mode 100644 apps/anatomy-cli/src/packed-consumer.spec.ts create mode 100644 apps/anatomy-cli/src/runAnatomyBundleCli.ts create mode 100644 apps/anatomy-cli/tsconfig.build.json create mode 100644 packages/anatomy/src/composition/AnatomyResourceLimits.ts create mode 100644 packages/anatomy/src/composition/checkInputBudget.ts create mode 100644 packages/anatomy/src/composition/compileAnatomyDefinition.ts create mode 100644 packages/anatomy/src/composition/composition.spec.ts create mode 100644 packages/anatomy/src/composition/createAnatomyFinding.ts create mode 100644 packages/anatomy/src/composition/index.ts create mode 100644 packages/anatomy/src/composition/planAnatomyBundle.ts create mode 100644 packages/anatomy/src/composition/queryAnatomyBundle.ts create mode 100644 packages/anatomy/src/composition/resolveAnatomyBundle.ts create mode 100644 packages/anatomy/src/composition/scanAnatomy.ts create mode 100644 packages/anatomy/src/composition/validateAnatomyBundle.ts create mode 100644 packages/anatomy/src/core/applyAnatomyExportChecks.ts create mode 100644 packages/anatomy/src/source/analyzeSourceExports.ts create mode 100644 packages/anatomy/src/source/index.ts create mode 100644 packages/anatomy/tsconfig.build.json delete mode 100644 packages/schemas/src/anatomy/AnatomyPublishedVersionListInputSchema.ts delete mode 100644 packages/schemas/src/anatomy/AnatomyVersionSchema.ts create mode 100644 packages/schemas/src/anatomy/createAnatomyNodeId.ts create mode 100644 packages/schemas/src/composition/AnatomyBundleQueryOutcomeSchema.ts create mode 100644 packages/schemas/src/composition/AnatomyBundleQueryRequestSchema.ts create mode 100644 packages/schemas/src/composition/AnatomyBundleSchema.ts create mode 100644 packages/schemas/src/composition/AnatomyBundleValidationOutcomeSchema.ts create mode 100644 packages/schemas/src/composition/AnatomyCompositionNodeSchema.ts create mode 100644 packages/schemas/src/composition/AnatomyDefinitionSchema.ts create mode 100644 packages/schemas/src/composition/AnatomyDiagnosticSchema.ts create mode 100644 packages/schemas/src/composition/AnatomyFindingSchema.ts create mode 100644 packages/schemas/src/composition/AnatomyMountSchema.ts create mode 100644 packages/schemas/src/composition/AnatomyOriginSchema.ts create mode 100644 packages/schemas/src/composition/AnatomyRuleSchema.ts create mode 100644 packages/schemas/src/composition/AnatomyScanOutcomeSchema.ts create mode 100644 packages/schemas/src/composition/AnatomyScanRequestSchema.ts create mode 100644 packages/schemas/src/composition/AnatomyTargetSchema.ts create mode 100644 packages/schemas/src/composition/index.ts create mode 100644 packages/schemas/tsconfig.build.json diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6015bbf..1df0f84 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -24,7 +24,7 @@ jobs: - uses: actions/setup-node@v4 with: - node-version: 22 + node-version-file: .nvmrc - name: Install dependencies run: bun install --frozen-lockfile diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 962d5d1..b7b02e4 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -38,7 +38,7 @@ jobs: bun-version: 1.3.11 - uses: actions/setup-node@v4 with: - node-version: 22 + node-version-file: .nvmrc - name: Install dependencies run: bun install --frozen-lockfile - name: Check documentation app @@ -71,7 +71,7 @@ jobs: bun-version: 1.3.11 - uses: actions/setup-node@v4 with: - node-version: 22 + node-version-file: .nvmrc - name: Install dependencies run: bun install --frozen-lockfile - uses: actions/download-artifact@v4 diff --git a/.nvmrc b/.nvmrc new file mode 100644 index 0000000..df6ae33 --- /dev/null +++ b/.nvmrc @@ -0,0 +1 @@ +24.21.0 diff --git a/README.md b/README.md index d3dfec1..dabcf6d 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ block · warn · allow result ## Requirements - Bun 1.3 or newer -- Node.js 18 or newer for the published CLI package when it is installed with npm or pnpm +- Node.js 24 or newer for the published CLI package when it is installed with npm or pnpm The repository is Bun-first for development. Published CLI releases are bundled as a standalone Node.js entry point, so registry installs do not need Bun. @@ -49,7 +49,7 @@ pnpm dlx anatomy-cli bunx anatomy-cli ``` -The one-shot installer requires Node.js 18+ on macOS, Linux or Windows. It +The one-shot installer requires Node.js 24+ on macOS, Linux or Windows. It copies the standalone CLI bundled in the downloaded `anatomy-cli` release to `~/.anatomy`, so it keeps working after the package manager clears its cache. No second package download, administrator privileges, or project dependency @@ -159,7 +159,7 @@ binding can use one built-in format, a custom regular expression, or both: ```json { "structure": { - "schemaVersion": 1, + "rootMode": "contents", "defaultPolicies": { "missingRequired": "block", "unexpectedEntry": "warn", @@ -273,7 +273,7 @@ Omit `--format json` for a readable summary of required files, quantities, inherited names, policies and conditional one-of alternatives. This summary describes constraints; it does not certify that the files pass validation. -Query JSON uses `contractVersion: 1`, `operation: "query"`, and these statuses: +Query JSON uses `operation: "query"` and these statuses: | Status | Meaning | | --- | --- | @@ -290,7 +290,7 @@ alternatives are conditional, not a list of files that must all be created. Always run a check to evaluate quantities, sibling alternatives and actual kinds. Check JSON preserves `conforms`, `summary`, and the existing issue fields, adding -`contractVersion: 1`, `operation: "check"`, definition/target metadata and +`operation: "check"`, definition/target metadata and `ignoredNames`. Each issue adds `rulePath` (a JSON Pointer into the definition), `expected` (the declared node), and `actual` (observed entry summaries). For missing-entry and one-of issues, `actual` lists siblings in the affected directory. @@ -302,10 +302,10 @@ A completed query exits `0` for every query status; inspect `status` before editing. Checks retain `0` for no blocking findings and `1` for blocking findings. Operational errors exit `2`; with `--format json`, stderr contains an `operation: "error"` JSON object and stdout has no success report. Missing or -invalid definitions, unsupported schema versions, unknown fields and unreadable +invalid definitions, unknown fields and unreadable targets are errors, not an absence of constraints. Unknown definition fields are -now rejected instead of silently removed; fix spelling or use supported version-1 -rules. Human check output and legacy target/definition flags remain supported. +rejected instead of silently removed; fix spelling or use the declared rules. +Use the explicit target and definition flags to select the scan scope. Queries describe declared structure independently of scan exclusions, so `--ignore` is only accepted for checks. By default, checks skip symbolic links and default @@ -358,8 +358,8 @@ the registry commands above gain this behavior; the existing 0.0.2 release predates it. Do not deploy homepage installer instructions ahead of that release. The root package is intentionally private. To publish a CLI release, authenticate -with npm and publish the app workspace with Bun; Bun replaces local `workspace:` -references while packing and the prepack hook creates the Node.js bundle: +with npm and publish the app workspace with Bun. Build the workspace first; the +prepack hook creates the CLI declarations and Node.js bundles: ```bash cd apps/anatomy-cli @@ -370,3 +370,96 @@ The package's `bin` entries must stay distinct: `anatomy-cli` dispatches to the installer by default; `anatomy` dispatches to the checker. Publish the three bundles (`main.js`, `index.js`, `install-main.js`) and the `bin/` launchers together. No separate installer package or install lifecycle script is needed. + +## Composition bundles and the SDK + +Use `nvm install && nvm use` at the repository root, then `bun install && bun run build`. +`.nvmrc` pins Node 24.21.0; package engines require Node 24+, and CI reads the same pin. +The registry release may lag behind the checkout; a local build does not publish packages. + +```bash +node apps/anatomy-cli/bin/anatomy.js /path/to/packages/db-schema \ + --bundle apps/anatomy-cli/anatomies/db-schema.bundle.json --format json + +# Query a mounted unit, relative to the target directory: +node apps/anatomy-cli/bin/anatomy.js /path/to/packages/db-schema \ + --bundle apps/anatomy-cli/anatomies/db-schema.bundle.json \ + --query src/tables/accounts --format json +``` + +`--bundle` is exclusive with `--definition` and `--ignore`; `--git-files` can select the +complete Git-visible inventory. Without it, the filesystem adapter excludes its standard +ignored names and symbolic links, as in single-definition scans. SDK callers explicitly +supply their inventory and declare its coverage. Exit codes are 0 for conformance, +1 for blocking findings, and 2 for invalid configuration or execution failure. + +The shipped bundle contains five independent definitions: Package, Tables Class, +Relations Class, Table Domain, and Relation Domain. A Domain is an **explicit directory**: + +```text +/ +├── index.ts +└── .table.ts (one or more) +``` + +A Class references this directory unit using `{ "kind": "composition", "ref": "table-domain", +"quantity": "one_or_more" }`. It reuses the directory itself, without creating +`accounts/accounts/`. Tables require at least one domain. Relations may have no domains, +but each existing relation domain requires at least one `.relation.ts` file. Extra +subdirectories and type-test files are rejected without modifying them. Relations may +refer across domains; this structure contract does not analyze relation-code semantics. + +A bundle has a logical `root` key and a `definitions` array of +`{ key, definition }` records. Definition keys are unique lowercase identifiers with +optional digits/hyphens. Every structure requires an explicit `rootMode`: + +- `entry`: `root` is a named directory with `quantity: "exactly_one"`. A composition + reference inherits its name and must omit `name`; the reference controls repetition. +- `contents`: `root.children` describes a selected directory's contents. A reference + must provide a single-segment mount `name`. + +Composition has no inline children, +alternatives, or source rules, and is not supported inside `one_of` alternatives. +There is one current contract without format-version selectors or historical Anatomy +versions. Each request resolves only its supplied definition snapshot. + +After building, the public packages expose ESM JavaScript and declarations: + +```ts +import { scanAnatomy, queryAnatomyBundle, validateAnatomyBundle } from '@anatomy-cli/anatomy'; + +const validation = validateAnatomyBundle(bundle); +const result = await scanAnatomy({ + bundle, + target: { kind: 'directory', name: 'db-schema', children: completeTree }, + coverage: { status: 'complete' }, + sources: {}, // Relative POSIX paths to source text, only needed for source rules. +}); +const query = queryAnatomyBundle({ bundle, path: 'src/tables/accounts', targetName: 'db-schema' }); +``` + +The SDK performs no filesystem, Git, network, or database reads and never executes target +source. Source analysis loads lazily when an export rule requires it. `@anatomy-cli/schemas` +exports runtime schemas and their inferred types. The lower-level `checkAnatomy` +matcher accepts normalized contents rules and a pre-analyzed source export map. + +A completed scan returns `status: "completed"`, `conforms`, `summary`, and `issues`. +Blocking findings are completed scans with `conforms: false`. Input/dependency/source +errors return `status: "error"`, `conforms: null`, and `diagnostics`, never a partial pass. +Findings carry original definition/rule pointers, actual mount paths, isolated captures, +effective policy origins, and stable `instanceKey`/`issueKey` values. Missing or +permission-omitted references both produce `unavailable_reference` without disclosing +unprovided definitions. The SDK rejects declared incomplete coverage; the caller remains +responsible for honestly reporting missing inventory. + +Resource limits are exported as `AnatomyResourceLimits`: 128 definitions, 100,000 input +objects, input nesting depth 128, reference depth 32, 10,000 mount instances, 5,000,000 +UTF-8 bytes per source, and 20,000,000 source bytes per request. Exceeding a limit returns +`resource_limit_exceeded`. + +`bun run quality` includes isolated tarball installation and real Node CLI/SDK tests; +these tests require npm registry access and retain their consumer fixtures under ignored +root `docs/verification/cod-420/`. Release order is schemas, core, then CLI after checking +scope permissions and registry versions. Publishing is a separate operation. Daedalus +integration additionally owns permissions, business-ID mapping, complete snapshots, +Findings mapping, and passing a selected root Anatomy through MCP scan orchestration. diff --git a/README.zh-CN.md b/README.zh-CN.md index 51e3552..e06d59b 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -30,7 +30,7 @@ block · warn · allow result ## 环境要求 - Bun 1.3 或更新版本 -- 通过 npm 或 pnpm 安装已发布 CLI 包时,需要 Node.js 18 或更新版本 +- 通过 npm 或 pnpm 安装已发布 CLI 包时,需要 Node.js 24 或更新版本 仓库开发以 Bun 为主。发布的 CLI 会打包为独立的 Node.js 入口,从包仓库安装时不需要 Bun。 @@ -44,7 +44,7 @@ pnpm dlx anatomy-cli bunx anatomy-cli ``` -一键安装器支持 macOS、Linux 和 Windows,需要 Node.js 18+。它将下载的 `anatomy-cli` 版本中已打包的独立 CLI 复制到 `~/.anatomy`,包管理器清理缓存后仍可使用。安装无需再次下载包、无需管理员权限,也不会修改项目依赖。包名保持为 `anatomy-cli`,日常使用的命令是 `anatomy`。 +一键安装器支持 macOS、Linux 和 Windows,需要 Node.js 24+。它将下载的 `anatomy-cli` 版本中已打包的独立 CLI 复制到 `~/.anatomy`,包管理器清理缓存后仍可使用。安装无需再次下载包、无需管理员权限,也不会修改项目依赖。包名保持为 `anatomy-cli`,日常使用的命令是 `anatomy`。 安装器会将其 `bin` 目录加入受支持的 Shell 配置文件或 Windows 用户 PATH。已有配置内容会保留,首次修改前会生成 `.anatomy-backup` 备份。安装后**打开新终端**,再运行: @@ -129,7 +129,7 @@ Anatomy JSON 定义只需包含供人阅读的元数据和结构约束。可以 ```json { "structure": { - "schemaVersion": 1, + "rootMode": "contents", "defaultPolicies": { "missingRequired": "block", "unexpectedEntry": "warn", @@ -206,7 +206,7 @@ bun run anatomy ./packages/services \ 省略 `--format json` 时,直接显示文件要求、数量、继承名称、策略和 one-of 条件选择的可读摘要。摘要描述的是约束,不代表实际文件已通过检查。 -查询 JSON 使用 `contractVersion: 1`、`operation: "query"`,状态含义如下: +查询 JSON 使用 `operation: "query"`,状态含义如下: | 状态 | 含义 | | --- | --- | @@ -217,9 +217,9 @@ bun run anatomy ./packages/services \ 响应包含定义及目标的绝对路径、有效策略、占位符捕获值、绑定约束、祖先数量约束、相关规则和所属 one-of 组。目录规则保留子树;可用 `captures` 替换后代中的继承占位符。one-of 的候选项是条件选择,不是全部必须创建的文件。数量、同级候选项和实际节点类型仍须在修改后执行检查。 -检查 JSON 保留 `conforms`、`summary` 和原有诊断字段,新增 `contractVersion: 1`、`operation: "check"`、定义及目标信息、`ignoredNames`。每条诊断新增 `rulePath`(定义中的 JSON Pointer)、`expected`(声明的节点)和 `actual`(实际条目摘要)。缺失节点与 one-of 诊断的 `actual` 列出受影响目录下的同级条目;意外节点的 `rulePath`、`expected` 为 null。用 `rulePath` 关联同一版定义的查询与检查:省略的 ID 每次解析都会重新生成,编辑定义后数组下标也可能变化。 +检查 JSON 保留 `conforms`、`summary` 和原有诊断字段,包含 `operation: "check"`、定义及目标信息、`ignoredNames`。每条诊断新增 `rulePath`(定义中的 JSON Pointer)、`expected`(声明的节点)和 `actual`(实际条目摘要)。缺失节点与 one-of 诊断的 `actual` 列出受影响目录下的同级条目;意外节点的 `rulePath`、`expected` 为 null。用 `rulePath` 关联同一版定义的查询与检查:省略的 ID 每次解析都会重新生成,编辑定义后数组下标也可能变化。 -查询完成时所有查询状态均返回退出码 `0`,Agent 应读取 `status` 再决定如何修改。检查仍以 `0` 表示没有阻断项、`1` 表示存在阻断项。运行错误返回 `2`;指定 `--format json` 时,stderr 输出 `operation: "error"` 的 JSON,stdout 不输出成功报告。定义缺失或无效、版本不支持、未知字段和目标不可读都属于错误,不能视为“没有约束”。未知定义字段现在会被拒绝,不再静默移除;需要修正拼写或使用已支持的版本 1 规则。原有人类可读检查输出和目标、定义参数保持可用。 +查询完成时所有查询状态均返回退出码 `0`,Agent 应读取 `status` 再决定如何修改。检查仍以 `0` 表示没有阻断项、`1` 表示存在阻断项。运行错误返回 `2`;指定 `--format json` 时,stderr 输出 `operation: "error"` 的 JSON,stdout 不输出成功报告。定义缺失或无效、未知字段和目标不可读都属于错误,不能视为“没有约束”。未知定义字段现在会被拒绝,不再静默移除;需要修正拼写或使用当前规则。目标和定义参数用于明确检查范围。 查询描述声明的结构,不应用扫描忽略规则,因此 `--ignore` 只接受于检查模式。默认检查跳过符号链接以及 `node_modules`、`dist` 等生成目录,报告会列出忽略名称。结构检查通过仅覆盖已采集文件树与已执行规则;类型和行为须另行验证。 @@ -243,7 +243,7 @@ bun run build 必须先发布包含一键安装器的新 `anatomy-cli` 版本,上面的包仓库安装命令才会具有对应行为。现有 `0.0.2` 版本发布于该功能之前。请勿在新版发布前部署包含一键安装说明的首页。 -根包有意设置为私有。发布 CLI 时,先登录 npm,再使用 Bun 发布应用工作区;Bun 会在打包时替换本地 `workspace:` 依赖,`prepack` 钩子会生成 Node.js 包: +根包有意设置为私有。发布 CLI 时,先构建工作区并登录 npm,再使用 Bun 发布应用工作区;`prepack` 钩子会生成 CLI 类型声明和 Node.js 构建文件: ```bash cd apps/anatomy-cli @@ -251,3 +251,54 @@ bun publish --access public ``` 包的两个 `bin` 入口必须保持独立:`anatomy-cli` 默认进入安装器,`anatomy` 进入检查器。发布时应同时包含三个构建文件(`main.js`、`index.js`、`install-main.js`)和 `bin/` 下的启动文件。无需单独的安装器包或安装生命周期脚本。 + +## 组合 Bundle 与 SDK + +在仓库根目录先运行 `nvm install && nvm use`,再运行 `bun install && bun run build`。`.nvmrc` 锁定 Node 24.21.0,所有包要求 Node 24+,CI 使用同一固定版本。npm 版本可能落后于本地代码,构建不等于发布。 + +```bash +node apps/anatomy-cli/bin/anatomy.js /path/to/packages/db-schema \ + --bundle apps/anatomy-cli/anatomies/db-schema.bundle.json --format json + +node apps/anatomy-cli/bin/anatomy.js /path/to/packages/db-schema \ + --bundle apps/anatomy-cli/anatomies/db-schema.bundle.json \ + --query src/tables/accounts --format json +``` + +`--bundle` 与 `--definition`、`--ignore` 互斥,可搭配 `--git-files` 使用完整的 Git 可见文件清单。普通文件系统模式沿用单定义扫描的默认忽略名称及符号链接排除规则;SDK 调用方自行提供清单并声明覆盖范围。退出码:符合结构为 0、阻断违规为 1、配置或执行错误为 2。 + +示例包含 Package、Tables Class、Relations Class、Table Domain、Relation Domain 五个独立定义。Domain 必须显示自身的目录: + +```text +/ +├── index.ts +└──
.table.ts (一个或多个) +``` + +Class 通过 `{ "kind": "composition", "ref": "table-domain", "quantity": "one_or_more" }` 引用整个目录单元,不会生成 `accounts/accounts/` 两层目录。Tables 至少包含一个域;Relations 可以没有域,但已有关系域至少需要一个 `.relation.ts` 文件。额外子目录与 type-test 文件会被拒绝,扫描不会删除文件。允许跨域关系引用,结构规则不验证关系代码语义。 + +Bundle 使用逻辑根键 `root` 和 `definitions: [{ key, definition }]`。key 必须唯一,以小写字母开头,可包含数字和中划线。所有结构必须明确指定 `rootMode`: + +- `entry`:root 是具名目录,数量为 `exactly_one`;引用继承根名,禁止重复指定 name,重复次数由引用的 quantity 控制。 +- `contents`:root.children 描述目录内容;引用必须提供单段挂载 name。 + +composition 不允许内联 children、alternatives 或源码规则,也不允许出现在 one_of 的 alternatives 中。只维护一套当前契约,不设置格式版本字段或历史 Anatomy 版本;每次请求只使用调用方提供的定义快照。 + +构建后的 `@anatomy-cli/anatomy` 提供 `validateAnatomyBundle`、`scanAnatomy`、`queryAnatomyBundle`,`@anatomy-cli/schemas` 提供运行时 Schema 与派生类型。两个包均输出 ESM JavaScript 和 d.ts。调用示例: + +```ts +const result = await scanAnatomy({ + bundle, + target: { kind: 'directory', name: 'db-schema', children: completeTree }, + coverage: { status: 'complete' }, + sources: {}, // 仅源码规则需要;键为扫描根下的相对 POSIX 路径。 +}); +``` + +SDK 不读取文件系统、Git、数据库或网络,不执行目标源码;需要导出校验时才加载共享源码分析器。底层 checkAnatomy 匹配器接收规范化的 contents 规则与预先分析的源码导出 Map。 + +扫描完成时返回 completed、conforms、summary 和 issues;结构阻断是 completed + conforms=false。配置、依赖、输入或源码错误返回 error + conforms=null + diagnostics,不返回部分通过。诊断携带原始定义/规则指针、实际挂载链、捕获值、策略来源和稳定身份。缺失与因权限未提供的引用统一为 unavailable_reference。SDK 拒绝调用方声明的 incomplete 树,但不能证明调用方没有隐瞒清单缺口。 + +公开限额 `AnatomyResourceLimits`:128 个定义、100,000 个输入对象、输入嵌套深度 128、引用深度 32、10,000 个挂载实例、单份源码 5,000,000 UTF-8 字节、全部源码 20,000,000 字节。超限返回 resource_limit_exceeded。 + +`bun run quality` 包含打包后独立安装与实际 Node CLI/SDK 测试;测试需要访问 npm registry,消费样例保留在被忽略的根 docs/verification/cod-420/ 中。发布前核对 scope 权限、npm 版本和 schemas→core→CLI 依赖顺序,真正发布是单独操作。Daedalus 仍负责权限、业务 ID 映射、完整仓库快照、Findings 映射,以及 MCP 根 Anatomy 选择与扫描编排的贯通。 diff --git a/anatomy.coverage.json b/anatomy.coverage.json index 8e9d5c8..182eb4b 100644 --- a/anatomy.coverage.json +++ b/anatomy.coverage.json @@ -1,5 +1,4 @@ { - "schemaVersion": 1, "exceptions": { "apps/anatomy-cli/bin/anatomy-cli.js": { "role": "entrypoint", @@ -734,13 +733,6 @@ "AnatomyPolicyValueSchema" ] }, - "packages/schemas/src/anatomy/AnatomyPublishedVersionListInputSchema.ts": { - "role": "schema", - "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", - "runtimeExports": [ - "AnatomyPublishedVersionListInputSchema" - ] - }, "packages/schemas/src/anatomy/AnatomyQuantitySchema.ts": { "role": "schema", "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", @@ -783,13 +775,6 @@ "AnatomySummarySchema" ] }, - "packages/schemas/src/anatomy/AnatomyVersionSchema.ts": { - "role": "schema", - "reason": "Exactly one named Zod schema matching the filename, with colocated inferred types.", - "runtimeExports": [ - "AnatomyVersionSchema" - ] - }, "packages/schemas/src/anatomy/index.ts": { "role": "barrel", "reason": "Public module aggregation; only relative wildcard re-exports are permitted.", @@ -806,6 +791,136 @@ "runtimeExports": [ "default" ] + }, + "packages/anatomy/src/composition/AnatomyResourceLimits.ts": { + "role": "data", + "reason": "Documented resource budget constants shared by validation and scanning.", + "runtimeExports": [ + "AnatomyResourceLimits" + ] + }, + "packages/anatomy/src/composition/composition.spec.ts": { + "role": "test", + "reason": "Executable regression suite with no public runtime exports.", + "runtimeExports": [] + }, + "packages/anatomy/src/composition/index.ts": { + "role": "barrel", + "reason": "Public module aggregation containing relative wildcard re-exports only.", + "runtimeExports": [] + }, + "packages/anatomy/src/source/index.ts": { + "role": "barrel", + "reason": "Public module aggregation containing relative wildcard re-exports only.", + "runtimeExports": [] + }, + "packages/schemas/src/composition/AnatomyBundleQueryOutcomeSchema.ts": { + "role": "schema", + "reason": "Runtime Zod schema with colocated inferred public types matching its filename.", + "runtimeExports": [ + "AnatomyBundleQueryOutcomeSchema" + ] + }, + "packages/schemas/src/composition/AnatomyBundleQueryRequestSchema.ts": { + "role": "schema", + "reason": "Runtime Zod schema with colocated inferred public types matching its filename.", + "runtimeExports": [ + "AnatomyBundleQueryRequestSchema" + ] + }, + "packages/schemas/src/composition/AnatomyBundleSchema.ts": { + "role": "schema", + "reason": "Runtime Zod schema with colocated inferred public types matching its filename.", + "runtimeExports": [ + "AnatomyBundleSchema" + ] + }, + "packages/schemas/src/composition/AnatomyBundleValidationOutcomeSchema.ts": { + "role": "schema", + "reason": "Runtime Zod schema with colocated inferred public types matching its filename.", + "runtimeExports": [ + "AnatomyBundleValidationOutcomeSchema" + ] + }, + "packages/schemas/src/composition/AnatomyCompositionNodeSchema.ts": { + "role": "schema", + "reason": "Runtime Zod schema with colocated inferred public types matching its filename.", + "runtimeExports": [ + "AnatomyCompositionNodeSchema" + ] + }, + "packages/schemas/src/composition/AnatomyDefinitionSchema.ts": { + "role": "schema", + "reason": "Runtime Zod schema with colocated inferred public types matching its filename.", + "runtimeExports": [ + "AnatomyDefinitionSchema" + ] + }, + "packages/schemas/src/composition/AnatomyDiagnosticSchema.ts": { + "role": "schema", + "reason": "Runtime Zod schema with colocated inferred public types matching its filename.", + "runtimeExports": [ + "AnatomyDiagnosticSchema" + ] + }, + "packages/schemas/src/composition/AnatomyFindingSchema.ts": { + "role": "schema", + "reason": "Runtime Zod schema with colocated inferred public types matching its filename.", + "runtimeExports": [ + "AnatomyFindingSchema" + ] + }, + "packages/schemas/src/composition/AnatomyMountSchema.ts": { + "role": "schema", + "reason": "Runtime Zod schema with colocated inferred public types matching its filename.", + "runtimeExports": [ + "AnatomyMountSchema" + ] + }, + "packages/schemas/src/composition/AnatomyOriginSchema.ts": { + "role": "schema", + "reason": "Runtime Zod schema with colocated inferred public types matching its filename.", + "runtimeExports": [ + "AnatomyOriginSchema" + ] + }, + "packages/schemas/src/composition/AnatomyScanOutcomeSchema.ts": { + "role": "schema", + "reason": "Runtime Zod schema with colocated inferred public types matching its filename.", + "runtimeExports": [ + "AnatomyScanOutcomeSchema" + ] + }, + "packages/schemas/src/composition/AnatomyScanRequestSchema.ts": { + "role": "schema", + "reason": "Runtime Zod schema with colocated inferred public types matching its filename.", + "runtimeExports": [ + "AnatomyScanRequestSchema" + ] + }, + "packages/schemas/src/composition/AnatomyTargetSchema.ts": { + "role": "schema", + "reason": "Runtime Zod schema with colocated inferred public types matching its filename.", + "runtimeExports": [ + "AnatomyTargetSchema" + ] + }, + "packages/schemas/src/composition/index.ts": { + "role": "barrel", + "reason": "Public module aggregation containing relative wildcard re-exports only.", + "runtimeExports": [] + }, + "apps/anatomy-cli/src/packed-consumer.spec.ts": { + "role": "test", + "reason": "Executable regression suite with no public runtime exports.", + "runtimeExports": [] + }, + "packages/schemas/src/composition/AnatomyRuleSchema.ts": { + "role": "schema", + "reason": "Runtime Zod schema with colocated inferred public types matching its filename.", + "runtimeExports": [ + "AnatomyRuleSchema" + ] } } } diff --git a/anatomy.json b/anatomy.json index bda3ad9..b2ea91a 100644 --- a/anatomy.json +++ b/anatomy.json @@ -2,7 +2,7 @@ "name": "Anatomy repository", "purpose": "Strict repository structure and function export contracts for all Git-visible files. Run anatomy . --git-files. Non-function source roles are reviewed in anatomy.coverage.json and verified by repository-contract.spec.ts.", "structure": { - "schemaVersion": 1, + "rootMode": "contents", "defaultPolicies": { "missingRequired": "block", "unexpectedEntry": "block", @@ -99,6 +99,13 @@ "kind": "file", "name": { "type": "literal", "value": "service-files.anatomy.json" }, "quantity": "exactly_one" + }, + { + "id": "45acc4f3-21e9-4759-87da-0ef20e0846d5", + "kind": "file", + "name": { "type": "literal", "value": "db-schema.bundle.json" }, + "quantity": "exactly_one", + "policyOverrides": {} } ] }, @@ -415,6 +422,24 @@ "kind": "file", "name": { "type": "literal", "value": "windowsPathScript.ts" }, "quantity": "exactly_one" + }, + { + "id": "f88299ba-3073-4d64-bd25-c4aa230bc587", + "kind": "file", + "name": { "type": "literal", "value": "packed-consumer.spec.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "7a251c8b-bdde-4daa-baff-b976f954274d", + "kind": "file", + "name": { "type": "literal", "value": "runAnatomyBundleCli.ts" }, + "quantity": "exactly_one", + "policyOverrides": {}, + "exports": { + "name": "file_stem", + "policy": "block" + } } ] }, @@ -422,6 +447,13 @@ "kind": "file", "name": { "type": "literal", "value": "tsconfig.json" }, "quantity": "exactly_one" + }, + { + "id": "9d9b5029-9e08-4f0b-a5e2-adf1eb8a370f", + "kind": "file", + "name": { "type": "literal", "value": "tsconfig.build.json" }, + "quantity": "exactly_one", + "policyOverrides": {} } ] }, @@ -1767,6 +1799,17 @@ "exports": { "name": "file_stem" } + }, + { + "id": "912e152f-207d-49e6-bf5e-19b09f4db772", + "kind": "file", + "name": { "type": "literal", "value": "applyAnatomyExportChecks.ts" }, + "quantity": "exactly_one", + "policyOverrides": {}, + "exports": { + "name": "file_stem", + "policy": "block" + } } ] }, @@ -1774,6 +1817,151 @@ "kind": "file", "name": { "type": "literal", "value": "index.ts" }, "quantity": "exactly_one" + }, + { + "id": "7296b4c2-1837-4fa9-96c0-fbf9dd278582", + "kind": "directory", + "name": { "type": "literal", "value": "composition" }, + "quantity": "exactly_one", + "policyOverrides": {}, + "children": [ + { + "id": "c452ab9d-0503-4d86-a20b-a7ae6bf000e5", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyResourceLimits.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "c983d55e-30ea-4903-9c38-25229b3d3dea", + "kind": "file", + "name": { "type": "literal", "value": "checkInputBudget.ts" }, + "quantity": "exactly_one", + "policyOverrides": {}, + "exports": { + "name": "file_stem", + "policy": "block" + } + }, + { + "id": "35224d28-2fac-474c-9a2c-6065b19610dc", + "kind": "file", + "name": { "type": "literal", "value": "compileAnatomyDefinition.ts" }, + "quantity": "exactly_one", + "policyOverrides": {}, + "exports": { + "name": "file_stem", + "policy": "block" + } + }, + { + "id": "78ba7db4-55fd-4447-a40c-0a258b86307a", + "kind": "file", + "name": { "type": "literal", "value": "composition.spec.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "bcb37a38-1a29-4db1-be49-993ab280c2f6", + "kind": "file", + "name": { "type": "literal", "value": "createAnatomyFinding.ts" }, + "quantity": "exactly_one", + "policyOverrides": {}, + "exports": { + "name": "file_stem", + "policy": "block" + } + }, + { + "id": "5f4556e6-134d-47b0-9df0-8703bcaf839b", + "kind": "file", + "name": { "type": "literal", "value": "index.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "1e5ee477-b3a6-4b66-87c2-35681b82e9ba", + "kind": "file", + "name": { "type": "literal", "value": "planAnatomyBundle.ts" }, + "quantity": "exactly_one", + "policyOverrides": {}, + "exports": { + "name": "file_stem", + "policy": "block" + } + }, + { + "id": "2488913b-2826-4c81-86fd-20ef44ab2f79", + "kind": "file", + "name": { "type": "literal", "value": "queryAnatomyBundle.ts" }, + "quantity": "exactly_one", + "policyOverrides": {}, + "exports": { + "name": "file_stem", + "policy": "block" + } + }, + { + "id": "60db4ef2-c3b3-422b-b7cd-74981701bbac", + "kind": "file", + "name": { "type": "literal", "value": "resolveAnatomyBundle.ts" }, + "quantity": "exactly_one", + "policyOverrides": {}, + "exports": { + "name": "file_stem", + "policy": "block" + } + }, + { + "id": "d0a7e0ad-4bdb-4e97-ab18-50a945dd4fad", + "kind": "file", + "name": { "type": "literal", "value": "scanAnatomy.ts" }, + "quantity": "exactly_one", + "policyOverrides": {}, + "exports": { + "name": "file_stem", + "policy": "block" + } + }, + { + "id": "ad7ef58f-dc28-4205-9d12-2a28bafd8b38", + "kind": "file", + "name": { "type": "literal", "value": "validateAnatomyBundle.ts" }, + "quantity": "exactly_one", + "policyOverrides": {}, + "exports": { + "name": "file_stem", + "policy": "block" + } + } + ] + }, + { + "id": "943960e8-b6e4-4762-9503-b1d9d219c0f7", + "kind": "directory", + "name": { "type": "literal", "value": "source" }, + "quantity": "exactly_one", + "policyOverrides": {}, + "children": [ + { + "id": "3e327f8b-8a4e-47db-8696-19f954acfe8a", + "kind": "file", + "name": { "type": "literal", "value": "analyzeSourceExports.ts" }, + "quantity": "exactly_one", + "policyOverrides": {}, + "exports": { + "name": "file_stem", + "policy": "block" + } + }, + { + "id": "71f16197-1e57-4e10-b7ba-7d2002f9d6ee", + "kind": "file", + "name": { "type": "literal", "value": "index.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + } + ] } ] }, @@ -1781,6 +1969,13 @@ "kind": "file", "name": { "type": "literal", "value": "tsconfig.json" }, "quantity": "exactly_one" + }, + { + "id": "5f32e69b-3f48-41f1-9e8d-1d3095b8c4a9", + "kind": "file", + "name": { "type": "literal", "value": "tsconfig.build.json" }, + "quantity": "exactly_one", + "policyOverrides": {} } ] }, @@ -1919,11 +2114,6 @@ "name": { "type": "literal", "value": "AnatomyPolicyValueSchema.ts" }, "quantity": "exactly_one" }, - { - "kind": "file", - "name": { "type": "literal", "value": "AnatomyPublishedVersionListInputSchema.ts" }, - "quantity": "exactly_one" - }, { "kind": "file", "name": { "type": "literal", "value": "AnatomyQuantitySchema.ts" }, @@ -1956,13 +2146,19 @@ }, { "kind": "file", - "name": { "type": "literal", "value": "AnatomyVersionSchema.ts" }, + "name": { "type": "literal", "value": "index.ts" }, "quantity": "exactly_one" }, { + "id": "9cd1a902-c57b-4768-9b79-20a77c246822", "kind": "file", - "name": { "type": "literal", "value": "index.ts" }, - "quantity": "exactly_one" + "name": { "type": "literal", "value": "createAnatomyNodeId.ts" }, + "quantity": "exactly_one", + "policyOverrides": {}, + "exports": { + "name": "file_stem", + "policy": "block" + } } ] }, @@ -1970,6 +2166,120 @@ "kind": "file", "name": { "type": "literal", "value": "index.ts" }, "quantity": "exactly_one" + }, + { + "id": "e34dac06-21bb-41ec-983f-9d2c56d1baff", + "kind": "directory", + "name": { "type": "literal", "value": "composition" }, + "quantity": "exactly_one", + "policyOverrides": {}, + "children": [ + { + "id": "c16be793-ca68-4a13-aebf-caca2a737ec6", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyBundleQueryOutcomeSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "dc5e87e5-27e8-43ec-b242-ad7587596b3f", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyBundleQueryRequestSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "b3570310-a071-47f6-a605-789f8745fcc3", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyBundleSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "478b7f75-b07c-46f9-a8bc-4c4c364b9e08", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyBundleValidationOutcomeSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "81de7097-5cc4-4bd9-b845-f3bb309e2623", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyCompositionNodeSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "20112a95-0688-4061-9d03-25c3ed304b55", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyDefinitionSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "655d4c82-4a83-4977-9cc8-4c56d95f015e", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyDiagnosticSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "2ca52c34-5deb-406f-b412-72846f67c9c0", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyFindingSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "70c660ca-9de5-476e-9ae4-74c3f734dcfb", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyMountSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "58a91a05-b06c-4ba7-9fc7-b9d0a0270146", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyOriginSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "2deacc34-b51c-439e-bc65-edd88ba74573", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyRuleSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "c836c891-fa08-4f48-875b-8c2d29b306d8", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyScanOutcomeSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "7a1e42f9-d401-41ba-a32b-965f09dca254", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyScanRequestSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "e45f2f14-03a7-41b7-acb7-1e3d3d2293ac", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyTargetSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "4c419753-1ea1-40ec-b11e-afd8813df35e", + "kind": "file", + "name": { "type": "literal", "value": "index.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + } + ] } ] }, @@ -1977,6 +2287,13 @@ "kind": "file", "name": { "type": "literal", "value": "tsconfig.json" }, "quantity": "exactly_one" + }, + { + "id": "36a6551f-1e39-4aa0-aed4-3d6f7f1d8271", + "kind": "file", + "name": { "type": "literal", "value": "tsconfig.build.json" }, + "quantity": "exactly_one", + "policyOverrides": {} } ] } @@ -1991,6 +2308,13 @@ "kind": "file", "name": { "type": "literal", "value": "vitest.config.ts" }, "quantity": "exactly_one" + }, + { + "id": "3ad4a0a9-e9bf-4b4c-a4ab-5759d78f21ea", + "kind": "file", + "name": { "type": "literal", "value": ".nvmrc" }, + "quantity": "exactly_one", + "policyOverrides": {} } ] } diff --git a/apps/anatomy-cli/anatomies/cli-source.anatomy.json b/apps/anatomy-cli/anatomies/cli-source.anatomy.json index 657e1f4..0f9cd0c 100644 --- a/apps/anatomy-cli/anatomies/cli-source.anatomy.json +++ b/apps/anatomy-cli/anatomies/cli-source.anatomy.json @@ -2,7 +2,7 @@ "name": "Anatomy CLI source modules", "purpose": "Focused copy of the repository contract for the CLI source directory; tests prevent divergence.", "structure": { - "schemaVersion": 1, + "rootMode": "contents", "defaultPolicies": { "missingRequired": "block", "unexpectedEntry": "block", @@ -289,6 +289,24 @@ "kind": "file", "name": { "type": "literal", "value": "windowsPathScript.ts" }, "quantity": "exactly_one" + }, + { + "id": "f88299ba-3073-4d64-bd25-c4aa230bc587", + "kind": "file", + "name": { "type": "literal", "value": "packed-consumer.spec.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "7a251c8b-bdde-4daa-baff-b976f954274d", + "kind": "file", + "name": { "type": "literal", "value": "runAnatomyBundleCli.ts" }, + "quantity": "exactly_one", + "policyOverrides": {}, + "exports": { + "name": "file_stem", + "policy": "block" + } } ] } diff --git a/apps/anatomy-cli/anatomies/db-schema.bundle.json b/apps/anatomy-cli/anatomies/db-schema.bundle.json new file mode 100644 index 0000000..91d0635 --- /dev/null +++ b/apps/anatomy-cli/anatomies/db-schema.bundle.json @@ -0,0 +1,238 @@ +{ + "root": "db-schema-package", + "definitions": [ + { + "key": "db-schema-package", + "definition": { + "name": "DB Schema Package", + "purpose": "Portable DB schema directory structure.", + "structure": { + "rootMode": "contents", + "defaultPolicies": { + "missingRequired": "block", + "unexpectedEntry": "block", + "nameMismatch": "block", + "nestingMismatch": "block" + }, + "root": { + "children": [ + { + "kind": "file", + "name": { + "type": "literal", + "value": "package.json" + }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { + "type": "literal", + "value": "tsconfig.json" + }, + "quantity": "exactly_one" + }, + { + "kind": "directory", + "name": { + "type": "literal", + "value": "src" + }, + "quantity": "exactly_one", + "children": [ + { + "kind": "file", + "name": { + "type": "literal", + "value": "index.ts" + }, + "quantity": "exactly_one" + }, + { + "kind": "composition", + "name": { + "type": "literal", + "value": "tables" + }, + "quantity": "exactly_one", + "ref": "tables-class", + "policyOverrides": {} + }, + { + "kind": "composition", + "name": { + "type": "literal", + "value": "relations" + }, + "quantity": "exactly_one", + "ref": "relations-class", + "policyOverrides": {} + } + ] + } + ] + }, + "rootMode": "contents" + } + } + }, + { + "key": "tables-class", + "definition": { + "name": "Tables Class", + "purpose": "Portable DB schema directory structure.", + "structure": { + "rootMode": "contents", + "defaultPolicies": { + "missingRequired": "block", + "unexpectedEntry": "block", + "nameMismatch": "block", + "nestingMismatch": "block" + }, + "root": { + "children": [ + { + "kind": "file", + "name": { + "type": "literal", + "value": "index.ts" + }, + "quantity": "exactly_one" + }, + { + "kind": "composition", + "quantity": "one_or_more", + "ref": "table-domain", + "policyOverrides": {} + } + ] + }, + "rootMode": "contents" + } + } + }, + { + "key": "relations-class", + "definition": { + "name": "Relations Class", + "purpose": "Portable DB schema directory structure.", + "structure": { + "rootMode": "contents", + "defaultPolicies": { + "missingRequired": "block", + "unexpectedEntry": "block", + "nameMismatch": "block", + "nestingMismatch": "block" + }, + "root": { + "children": [ + { + "kind": "file", + "name": { + "type": "literal", + "value": "index.ts" + }, + "quantity": "exactly_one" + }, + { + "kind": "composition", + "quantity": "zero_or_more", + "ref": "relation-domain", + "policyOverrides": {} + } + ] + }, + "rootMode": "contents" + } + } + }, + { + "key": "table-domain", + "definition": { + "name": "Table Domain", + "purpose": "Portable DB schema directory structure.", + "structure": { + "rootMode": "contents", + "defaultPolicies": { + "missingRequired": "block", + "unexpectedEntry": "block", + "nameMismatch": "block", + "nestingMismatch": "block" + }, + "root": { + "children": [ + { + "kind": "file", + "name": { + "type": "literal", + "value": "index.ts" + }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { + "type": "placeholder", + "value": "
.table.ts" + }, + "quantity": "one_or_more" + } + ], + "kind": "directory", + "name": { + "type": "placeholder", + "value": "" + }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + "rootMode": "entry" + } + } + }, + { + "key": "relation-domain", + "definition": { + "name": "Relation Domain", + "purpose": "Portable DB schema directory structure.", + "structure": { + "rootMode": "contents", + "defaultPolicies": { + "missingRequired": "block", + "unexpectedEntry": "block", + "nameMismatch": "block", + "nestingMismatch": "block" + }, + "root": { + "children": [ + { + "kind": "file", + "name": { + "type": "literal", + "value": "index.ts" + }, + "quantity": "exactly_one" + }, + { + "kind": "file", + "name": { + "type": "placeholder", + "value": "
.relation.ts" + }, + "quantity": "one_or_more" + } + ], + "kind": "directory", + "name": { + "type": "placeholder", + "value": "" + }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + "rootMode": "entry" + } + } + } + ] +} diff --git a/apps/anatomy-cli/anatomies/drizzle-table-files.anatomy.json b/apps/anatomy-cli/anatomies/drizzle-table-files.anatomy.json index 064738c..228129e 100644 --- a/apps/anatomy-cli/anatomies/drizzle-table-files.anatomy.json +++ b/apps/anatomy-cli/anatomies/drizzle-table-files.anatomy.json @@ -2,7 +2,7 @@ "name": "Drizzle table files", "purpose": "Require Drizzle table definition files to use the *.table.ts suffix while allowing the tables barrel and optional JSON support modules.", "structure": { - "schemaVersion": 1, + "rootMode": "contents", "defaultPolicies": { "missingRequired": "block", "unexpectedEntry": "block", diff --git a/apps/anatomy-cli/anatomies/service-files.anatomy.json b/apps/anatomy-cli/anatomies/service-files.anatomy.json index 9f6a9d2..d14572d 100644 --- a/apps/anatomy-cli/anatomies/service-files.anatomy.json +++ b/apps/anatomy-cli/anatomies/service-files.anatomy.json @@ -2,7 +2,7 @@ "name": "Service files", "purpose": "Allow simple *.service.ts modules and PascalCase *Service folder components with conventional helper, method, schema, and error submodules.", "structure": { - "schemaVersion": 1, + "rootMode": "contents", "defaultPolicies": { "missingRequired": "block", "unexpectedEntry": "block", diff --git a/apps/anatomy-cli/package.json b/apps/anatomy-cli/package.json index 98593e3..edfaedd 100644 --- a/apps/anatomy-cli/package.json +++ b/apps/anatomy-cli/package.json @@ -31,10 +31,13 @@ "anatomy": "./bin/anatomy.js" }, "exports": { - ".": "./dist/index.js" + ".": { + "types": "./dist/index.d.ts", + "default": "./dist/index.js" + } }, "scripts": { - "build": "bun build src/main.ts --target=node --outfile=dist/main.js && bun build src/index.ts --target=node --outfile=dist/index.js && bun build src/install-main.ts --target=node --outfile=dist/install-main.js", + "build": "rm -rf dist && tsc -p tsconfig.build.json && bun build src/main.ts --target=node --outfile=dist/main.js && bun build src/index.ts --target=node --outfile=dist/index.js && bun build src/install-main.ts --target=node --outfile=dist/install-main.js", "dev": "bun --watch src/main.ts", "start": "bun src/main.ts", "scan:self": "bun src/main.ts ../.. --git-files", @@ -46,16 +49,19 @@ "prepack": "bun run build" }, "engines": { - "node": ">=18", + "node": ">=24", "bun": ">=1.3.0" }, "devDependencies": { - "@anatomy-cli/anatomy": "workspace:*", - "@anatomy-cli/schemas": "workspace:*", - "neverthrow": "^8.2.0", "@types/node": "^25.9.2", "oxlint": "^1.59.0", "typescript": "5.9.2", "vitest": "^4.1.8" + }, + "types": "./dist/index.d.ts", + "dependencies": { + "@anatomy-cli/anatomy": "^0.1.0", + "@anatomy-cli/schemas": "^0.1.0", + "neverthrow": "^8.2.0" } } diff --git a/apps/anatomy-cli/src/AnatomyCliUsage.ts b/apps/anatomy-cli/src/AnatomyCliUsage.ts index 7064f0b..26afaa8 100644 --- a/apps/anatomy-cli/src/AnatomyCliUsage.ts +++ b/apps/anatomy-cli/src/AnatomyCliUsage.ts @@ -6,6 +6,7 @@ export const AnatomyCliUsage = [ "", "Options:", " -d, --definition Anatomy JSON (default: nearest anatomy.json)", + " --bundle Composition bundle (exclusive with --definition)", " -t, --target Alternate form of the target argument", " --format human or json (default: human)", " --query Query constraints relative to target (path may not exist)", diff --git a/apps/anatomy-cli/src/DefaultIgnoredNames.ts b/apps/anatomy-cli/src/DefaultIgnoredNames.ts index aa50187..be96617 100644 --- a/apps/anatomy-cli/src/DefaultIgnoredNames.ts +++ b/apps/anatomy-cli/src/DefaultIgnoredNames.ts @@ -1,4 +1,4 @@ -import { DefaultAnatomyDefinitionFileName } from "./DefaultAnatomyDefinitionFileName"; +import { DefaultAnatomyDefinitionFileName } from "./DefaultAnatomyDefinitionFileName.js"; export const DefaultIgnoredNames = [ ".git", diff --git a/apps/anatomy-cli/src/agent-workflow.spec.ts b/apps/anatomy-cli/src/agent-workflow.spec.ts index 7a70dc9..acb3091 100644 --- a/apps/anatomy-cli/src/agent-workflow.spec.ts +++ b/apps/anatomy-cli/src/agent-workflow.spec.ts @@ -2,18 +2,18 @@ import { AnatomyCheckWithDiagnosticsSchema, AnatomyQueryWithConstraintsSchema } import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; import { join, resolve } from "node:path"; import { afterEach, beforeEach, describe, expect, it } from "vitest"; -import { collectFileTree } from "./collectFileTree"; -import { findAnatomyDefinition } from "./findAnatomyDefinition"; -import { formatAgentError } from "./formatAgentError"; -import { readAnatomyDefinition } from "./readAnatomyDefinition"; -import { runAnatomyCli, type AnatomyCliDependencies } from "./runAnatomyCli"; +import { collectFileTree } from "./collectFileTree.js"; +import { findAnatomyDefinition } from "./findAnatomyDefinition.js"; +import { formatAgentError } from "./formatAgentError.js"; +import { readAnatomyDefinition } from "./readAnatomyDefinition.js"; +import { runAnatomyCli, type AnatomyCliDependencies } from "./runAnatomyCli.js"; const verificationRoot = resolve(import.meta.dirname, "../../../docs/verification/agent-workflow-tests"); let directory: string; const document = () => ({ name: "Services", purpose: "Plan before creating modules", structure: { - schemaVersion: 1, + rootMode: "contents", defaultPolicies: { missingRequired: "block", unexpectedEntry: "block", nameMismatch: "block", nestingMismatch: "block" }, bindings: { Name: { format: "PascalCase" } }, root: { children: [{ diff --git a/apps/anatomy-cli/src/analyze-source-exports.spec.ts b/apps/anatomy-cli/src/analyze-source-exports.spec.ts index be80c8b..68cb6d5 100644 --- a/apps/anatomy-cli/src/analyze-source-exports.spec.ts +++ b/apps/anatomy-cli/src/analyze-source-exports.spec.ts @@ -1,5 +1,5 @@ import { describe, expect, it } from "vitest"; -import { analyzeSourceExports } from "./analyzeSourceExports"; +import { analyzeSourceExports } from "./analyzeSourceExports.js"; describe("JavaScript and TypeScript export analysis", () => { it.each([ @@ -16,9 +16,9 @@ describe("JavaScript and TypeScript export analysis", () => { "export function getUser(id: string): void; export function getUser(id: number): void; export function getUser(id: string | number) {}", "export type User = { id: string }; export interface Options {} export function getUser() {}", "type User = {}; interface Options {} export { User, Options }; export const getUser = () => {};", - "import type { User } from './user'; export { User }; export function getUser() {}", - "export type * from './types'; export function getUser() {}", - "export { type User } from './types'; export function getUser() {}", + "import type { User } from './user.js'; export { User }; export function getUser() {}", + "export type * from './types.js'; export function getUser() {}", + "export { type User } from './types.js'; export function getUser() {}", "// export function fake() {}\nconst text = 'export const fake = 1'; export function getUser() {}", "throw new Error('This source must never execute'); export function getUser() {}", ])("finds local functions without executing source: %s", (source) => { @@ -52,9 +52,9 @@ describe("JavaScript and TypeScript export analysis", () => { it.each([ "export function getUser( {", - "export * from './other';", - "export { getUser } from './other';", - "import { getUser } from './other'; export { getUser };", + "export * from './other.js';", + "export { getUser } from './other.js';", + "import { getUser } from './other.js'; export { getUser };", "export const getUser = createFunction();", "export declare function getUser(): void;", "const one = two; const two = one; export { one };", diff --git a/apps/anatomy-cli/src/analyzeSourceExports.ts b/apps/anatomy-cli/src/analyzeSourceExports.ts index 087afe3..2b7ecb7 100644 --- a/apps/anatomy-cli/src/analyzeSourceExports.ts +++ b/apps/anatomy-cli/src/analyzeSourceExports.ts @@ -1,162 +1,2 @@ -import ts from "typescript"; -import { err, ok, Result, type Result as ResultType } from "neverthrow"; -import { AnatomySourceAnalysisError } from "@anatomy-cli/anatomy/core"; -import type { AnatomySourceExports } from "@anatomy-cli/schemas"; - -const hasModifier = (node: ts.Node, kind: ts.SyntaxKind) => - ts.canHaveModifiers(node) && ts.getModifiers(node)?.some((modifier) => modifier.kind === kind) === true; - -export const analyzeSourceExports = ( - path: string, - content: string, -): ResultType => { - const fail = (message: string) => err(new AnatomySourceAnalysisError(path, `${path}: ${message}`)); - if (!/\.(?:[cm]?[jt]s|[jt]sx)$/i.test(path) || /\.d\.[cm]?ts$/i.test(path)) { - return fail("Function export checks require a JavaScript or TypeScript implementation file"); - } - const parsed = Result.fromThrowable(() => { - const options: ts.CompilerOptions = { noLib: true, noResolve: true, types: [], allowJs: true, target: ts.ScriptTarget.Latest }; - const host = ts.createCompilerHost(options); - host.getSourceFile = (filename, languageVersion) => filename === path - ? ts.createSourceFile(filename, content, languageVersion, true) : undefined; - host.fileExists = (filename) => filename === path; - host.readFile = (filename) => filename === path ? content : undefined; - const program = ts.createProgram([path], options, host); - return { file: program.getSourceFile(path), diagnostics: program.getSyntacticDiagnostics() }; - }, (cause) => new AnatomySourceAnalysisError(path, `Unable to parse ${path}: ${String(cause)}`))(); - if (parsed.isErr()) return err(parsed.error); - const { file, diagnostics } = parsed.value; - if (!file) return fail("Unable to create source file"); - if (diagnostics.length) return fail(ts.flattenDiagnosticMessageText(diagnostics[0]!.messageText, "\n")); - - const locals = new Map(); - const register = (name: string, node: ts.Node) => locals.set(name, [...locals.get(name) ?? [], node]); - const bindingNames = (name: ts.BindingName): string[] => ts.isIdentifier(name) - ? [name.text] : name.elements.flatMap((element) => ts.isOmittedExpression(element) ? [] : bindingNames(element.name)); - for (const statement of file.statements) { - if (ts.isVariableStatement(statement)) { - for (const declaration of statement.declarationList.declarations) { - for (const name of bindingNames(declaration.name)) register(name, declaration); - } - } else if (ts.isImportDeclaration(statement)) { - const clause = statement.importClause; - if (clause?.name) register(clause.name.text, clause); - if (clause?.namedBindings) { - if (ts.isNamespaceImport(clause.namedBindings)) register(clause.namedBindings.name.text, clause); - else for (const specifier of clause.namedBindings.elements) register(specifier.name.text, specifier); - } - } else if ("name" in statement && statement.name && ts.isIdentifier(statement.name as ts.Node)) { - register((statement.name as ts.Identifier).text, statement); - } - } - - const resolveExpression = (expression: ts.Expression, seen: Set): "function" | "value" | "unknown" => { - if (ts.isArrowFunction(expression) || ts.isFunctionExpression(expression)) return "function"; - if (ts.isParenthesizedExpression(expression) || ts.isAsExpression(expression) || - ts.isTypeAssertionExpression(expression) || ts.isSatisfiesExpression(expression) || ts.isNonNullExpression(expression)) { - return resolveExpression(expression.expression, seen); - } - if (ts.isIdentifier(expression)) { - const kind = resolveLocal(expression.text, seen); - return kind === "type" ? "unknown" : kind; - } - if (ts.isCallExpression(expression) || ts.isAwaitExpression(expression) || ts.isPropertyAccessExpression(expression) || - ts.isElementAccessExpression(expression) || ts.isConditionalExpression(expression)) return "unknown"; - return "value"; - }; - const resolveLocal = (name: string, seen = new Set()): "function" | "value" | "type" | "unknown" => { - if (seen.has(name)) return "unknown"; - const declarations = locals.get(name); - if (!declarations?.length) return "unknown"; - const next = new Set([...seen, name]); - const runtime = declarations.filter((node) => !ts.isInterfaceDeclaration(node) && !ts.isTypeAliasDeclaration(node)); - if (!runtime.length) return "type"; - const functions = runtime.filter(ts.isFunctionDeclaration); - if (functions.length === runtime.length) return functions.filter((node) => node.body).length === 1 ? "function" : "unknown"; - if (runtime.length !== 1) return "unknown"; - const node = runtime[0]!; - if (ts.isImportClause(node)) return node.isTypeOnly ? "type" : "unknown"; - if (ts.isImportSpecifier(node)) return node.isTypeOnly || node.parent.parent.isTypeOnly ? "type" : "unknown"; - if (hasModifier(node, ts.SyntaxKind.DeclareKeyword)) return "unknown"; - if (ts.isVariableDeclaration(node)) { - if (!ts.isIdentifier(node.name) || !node.initializer) return "unknown"; - return resolveExpression(node.initializer, next); - } - return "value"; - }; - - let commonJs = false; - const isCommonJsTarget = (node: ts.Node): boolean => { - if (ts.isIdentifier(node)) return node.text === "exports"; - if (ts.isPropertyAccessExpression(node)) return isCommonJsTarget(node.expression) || - (ts.isIdentifier(node.expression) && node.expression.text === "module" && node.name.text === "exports"); - if (ts.isElementAccessExpression(node)) return isCommonJsTarget(node.expression) || - (ts.isIdentifier(node.expression) && node.expression.text === "module" && ts.isStringLiteral(node.argumentExpression) && node.argumentExpression.text === "exports"); - return false; - }; - const inspect = (node: ts.Node): void => { - if (ts.isBinaryExpression(node) && node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && - node.operatorToken.kind <= ts.SyntaxKind.LastAssignment && isCommonJsTarget(node.left)) commonJs = true; - if (ts.isCallExpression(node) && node.arguments.some(isCommonJsTarget)) commonJs = true; - ts.forEachChild(node, inspect); - }; - inspect(file); - if (commonJs) return fail("CommonJS export mutations are not supported; use local ES module exports"); - - const exported: AnatomySourceExports = []; - const exportedFunctions = new Set(); - const addLocal = (local: string, name: string): ResultType => { - const kind = resolveLocal(local); - if (kind === "unknown") return fail(`Cannot determine whether export "${name}" is a local function; imported, ambient and computed exports are not supported`); - if (kind !== "type") exported.push({ name, kind }); - return ok(undefined); - }; - - for (const statement of file.statements) { - if (ts.isExportDeclaration(statement)) { - if (statement.isTypeOnly) continue; - if (statement.moduleSpecifier) { - if (statement.exportClause && ts.isNamedExports(statement.exportClause) && statement.exportClause.elements.every((item) => item.isTypeOnly)) continue; - return fail("Runtime re-exports are not supported; export a local function"); - } - if (!statement.exportClause || !ts.isNamedExports(statement.exportClause)) return fail("Unsupported export declaration"); - for (const item of statement.exportClause.elements) { - if (item.isTypeOnly) continue; - const added = addLocal((item.propertyName ?? item.name).text, item.name.text); - if (added.isErr()) return err(added.error); - } - continue; - } - if (ts.isExportAssignment(statement)) { - if (statement.isExportEquals) return fail("CommonJS export assignments are not supported"); - const kind = resolveExpression(statement.expression, new Set()); - if (kind === "unknown") return fail("Cannot resolve computed default export"); - exported.push({ name: "default", kind }); - continue; - } - if (!hasModifier(statement, ts.SyntaxKind.ExportKeyword)) continue; - if (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement)) continue; - if (hasModifier(statement, ts.SyntaxKind.DeclareKeyword)) return fail("Ambient runtime exports cannot be verified in an implementation file"); - const isDefault = hasModifier(statement, ts.SyntaxKind.DefaultKeyword); - if (ts.isFunctionDeclaration(statement)) { - if (!statement.name) { - exported.push({ name: "default", kind: "function" }); - continue; - } - if (exportedFunctions.has(statement.name.text)) continue; - exportedFunctions.add(statement.name.text); - const added = addLocal(statement.name.text, isDefault ? "default" : statement.name.text); - if (added.isErr()) return err(added.error); - } else if (ts.isVariableStatement(statement)) { - for (const declaration of statement.declarationList.declarations) { - for (const name of bindingNames(declaration.name)) { - const added = addLocal(name, name); - if (added.isErr()) return err(added.error); - } - } - } else if (ts.isClassDeclaration(statement) || ts.isEnumDeclaration(statement) || ts.isModuleDeclaration(statement)) { - exported.push({ name: isDefault ? "default" : statement.name?.text ?? "default", kind: "value" }); - } else return fail("Unsupported runtime export declaration"); - } - return ok(exported); -}; +import { analyzeSourceExports as analyze } from "@anatomy-cli/anatomy/source"; +export const analyzeSourceExports = (path: string, content: string) => analyze(path, content); diff --git a/apps/anatomy-cli/src/cli-arguments.spec.ts b/apps/anatomy-cli/src/cli-arguments.spec.ts index 0e7f28e..f409c0c 100644 --- a/apps/anatomy-cli/src/cli-arguments.spec.ts +++ b/apps/anatomy-cli/src/cli-arguments.spec.ts @@ -1,5 +1,5 @@ import { describe, expect, it } from "vitest"; -import { parseCliArguments } from "./parseCliArguments"; +import { parseCliArguments } from "./parseCliArguments.js"; describe("parseCliArguments", () => { it("supports query mode without reserving existing target directory names", () => { @@ -24,6 +24,7 @@ describe("parseCliArguments", () => { expect(result).toEqual({ definitionPath: "anatomy.json", + bundlePath: null, targetPath: "src", format: "json", ignore: ["generated", "temp", "fixtures"], @@ -67,3 +68,12 @@ describe("parseCliArguments", () => { expect(parseCliArguments(["src", "--format", "xml"]).isErr()).toBe(true); }); }); + +describe("composition bundle arguments",()=>{ + it("accepts a bundle and a Git-visible target",()=>{ + expect(parseCliArguments(["src","--bundle","bundle.json","--git-files"])._unsafeUnwrap()).toMatchObject({bundlePath:"bundle.json",definitionPath:null,gitFiles:true}); + }); + it.each([["--bundle"],["--bundle","a","--bundle","b"],["--bundle","a","--definition","b"],["--bundle","a","--ignore","src"]].map(args=>({args})))("rejects ambiguous or incomplete bundle options $args",({args})=>{ + expect(parseCliArguments(args).isErr()).toBe(true); + }); +}); diff --git a/apps/anatomy-cli/src/cli.spec.ts b/apps/anatomy-cli/src/cli.spec.ts index b11a886..e741d3a 100644 --- a/apps/anatomy-cli/src/cli.spec.ts +++ b/apps/anatomy-cli/src/cli.spec.ts @@ -1,10 +1,10 @@ import { createEmptyAnatomyDraft } from "@anatomy-cli/anatomy/core"; import { err, ok } from "neverthrow"; import { describe, expect, it, vi } from "vitest"; -import { AnatomyCliExitCode } from "./AnatomyCliExitCode"; -import { AnatomyDefinitionFileError } from "./AnatomyDefinitionFileError"; -import { AnatomyFileTreeError } from "./AnatomyFileTreeError"; -import { runAnatomyCli, type AnatomyCliDependencies } from "./runAnatomyCli"; +import { AnatomyCliExitCode } from "./AnatomyCliExitCode.js"; +import { AnatomyDefinitionFileError } from "./AnatomyDefinitionFileError.js"; +import { AnatomyFileTreeError } from "./AnatomyFileTreeError.js"; +import { runAnatomyCli, type AnatomyCliDependencies } from "./runAnatomyCli.js"; const definition = createEmptyAnatomyDraft("Empty", "Allows an empty root"); diff --git a/apps/anatomy-cli/src/collectFileTree.ts b/apps/anatomy-cli/src/collectFileTree.ts index c73fa13..58fe484 100644 --- a/apps/anatomy-cli/src/collectFileTree.ts +++ b/apps/anatomy-cli/src/collectFileTree.ts @@ -2,8 +2,8 @@ import type { AnatomyFileTreeEntry } from "@anatomy-cli/anatomy/core"; import { err, ok, Result, ResultAsync } from "neverthrow"; import { readdir } from "node:fs/promises"; import { join, resolve } from "node:path"; -import { AnatomyFileTreeError } from "./AnatomyFileTreeError"; -import { DefaultIgnoredNames } from "./DefaultIgnoredNames"; +import { AnatomyFileTreeError } from "./AnatomyFileTreeError.js"; +import { DefaultIgnoredNames } from "./DefaultIgnoredNames.js"; const collectDirectory = async ( directory: string, diff --git a/apps/anatomy-cli/src/collectGitFileTree.ts b/apps/anatomy-cli/src/collectGitFileTree.ts index 218da70..3b43d2e 100644 --- a/apps/anatomy-cli/src/collectGitFileTree.ts +++ b/apps/anatomy-cli/src/collectGitFileTree.ts @@ -4,7 +4,7 @@ import { execFile } from "node:child_process"; import { lstat } from "node:fs/promises"; import { resolve } from "node:path"; import { promisify } from "node:util"; -import { AnatomyFileTreeError } from "./AnatomyFileTreeError"; +import { AnatomyFileTreeError } from "./AnatomyFileTreeError.js"; export const collectGitFileTree = async ( targetPath: string, diff --git a/apps/anatomy-cli/src/collectSourceExports.ts b/apps/anatomy-cli/src/collectSourceExports.ts index eb7b40d..751d00f 100644 --- a/apps/anatomy-cli/src/collectSourceExports.ts +++ b/apps/anatomy-cli/src/collectSourceExports.ts @@ -3,7 +3,7 @@ import { resolve } from "node:path"; import { err, ok, ResultAsync, type Result } from "neverthrow"; import { AnatomySourceAnalysisError } from "@anatomy-cli/anatomy/core"; import type { AnatomyFunctionExportCheck, AnatomySourceExports } from "@anatomy-cli/schemas"; -import { analyzeSourceExports } from "./analyzeSourceExports"; +import { analyzeSourceExports } from "./analyzeSourceExports.js"; export const collectSourceExports = async ( targetPath: string, diff --git a/apps/anatomy-cli/src/configurePath.ts b/apps/anatomy-cli/src/configurePath.ts index 02acf7d..564721c 100644 --- a/apps/anatomy-cli/src/configurePath.ts +++ b/apps/anatomy-cli/src/configurePath.ts @@ -2,9 +2,9 @@ import { err, ok, Result } from "neverthrow"; import { spawnSync } from "node:child_process"; import { appendFileSync, constants, copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs"; import { dirname } from "node:path"; -import { AnatomyInstallError } from "./AnatomyInstallError"; -import { getPathPlan } from "./getPathPlan"; -import { windowsPathScript } from "./windowsPathScript"; +import { AnatomyInstallError } from "./AnatomyInstallError.js"; +import { getPathPlan } from "./getPathPlan.js"; +import { windowsPathScript } from "./windowsPathScript.js"; export const configurePath = ( bin: string, diff --git a/apps/anatomy-cli/src/filesystem.spec.ts b/apps/anatomy-cli/src/filesystem.spec.ts index c7519dc..146a47d 100644 --- a/apps/anatomy-cli/src/filesystem.spec.ts +++ b/apps/anatomy-cli/src/filesystem.spec.ts @@ -3,9 +3,9 @@ import { mkdir, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { afterEach, describe, expect, it } from "vitest"; -import { collectFileTree } from "./collectFileTree"; -import { findAnatomyDefinition } from "./findAnatomyDefinition"; -import { readAnatomyDefinition } from "./readAnatomyDefinition"; +import { collectFileTree } from "./collectFileTree.js"; +import { findAnatomyDefinition } from "./findAnatomyDefinition.js"; +import { readAnatomyDefinition } from "./readAnatomyDefinition.js"; const testDirectory = join(process.cwd(), ".anatomy-cli-test"); const missingDefinitionDirectory = join( diff --git a/apps/anatomy-cli/src/findAnatomyDefinition.ts b/apps/anatomy-cli/src/findAnatomyDefinition.ts index a556e61..38bc84a 100644 --- a/apps/anatomy-cli/src/findAnatomyDefinition.ts +++ b/apps/anatomy-cli/src/findAnatomyDefinition.ts @@ -1,8 +1,8 @@ import { err, ok, Result, ResultAsync } from "neverthrow"; import { access } from "node:fs/promises"; import { dirname, join, resolve } from "node:path"; -import { AnatomyDefinitionFileError } from "./AnatomyDefinitionFileError"; -import { DefaultAnatomyDefinitionFileName } from "./DefaultAnatomyDefinitionFileName"; +import { AnatomyDefinitionFileError } from "./AnatomyDefinitionFileError.js"; +import { DefaultAnatomyDefinitionFileName } from "./DefaultAnatomyDefinitionFileName.js"; export const findAnatomyDefinition = async ( targetPath: string, diff --git a/apps/anatomy-cli/src/format-agent-result.spec.ts b/apps/anatomy-cli/src/format-agent-result.spec.ts index a4c5e0c..0d4e5ad 100644 --- a/apps/anatomy-cli/src/format-agent-result.spec.ts +++ b/apps/anatomy-cli/src/format-agent-result.spec.ts @@ -1,12 +1,12 @@ import { queryAnatomy } from "@anatomy-cli/anatomy/core"; import { AnatomyDraftInputSchema } from "@anatomy-cli/schemas"; import { describe, expect, it } from "vitest"; -import { formatAgentQuery } from "./formatAgentQuery"; +import { formatAgentQuery } from "./formatAgentQuery.js"; const definition = AnatomyDraftInputSchema.parse({ name: "Readable query", purpose: "Show constraints before editing", structure: { - schemaVersion: 1, + rootMode: "contents", defaultPolicies: { missingRequired: "block", unexpectedEntry: "block", nameMismatch: "block", nestingMismatch: "block" }, bindings: { Name: { format: "PascalCase" } }, root: { children: [{ @@ -60,6 +60,6 @@ describe("human query output", () => { const query = queryAnatomy(definition, "UserService/UserService.ts")._unsafeUnwrap(); const report = JSON.parse(formatAgentQuery(query, definition, "anatomy.json", ".", "json")); expect(report).toMatchObject(query); - expect(report.definition).toMatchObject({ name: definition.name, schemaVersion: 1 }); + expect(report.definition).toMatchObject({ name: definition.name, rootMode: "contents" }); }); }); diff --git a/apps/anatomy-cli/src/formatAgentCheck.ts b/apps/anatomy-cli/src/formatAgentCheck.ts index 41c458d..24b20cc 100644 --- a/apps/anatomy-cli/src/formatAgentCheck.ts +++ b/apps/anatomy-cli/src/formatAgentCheck.ts @@ -1,7 +1,7 @@ import { AnatomyCheckCode, anatomyRulePaths, type AnatomyCheckResult, type AnatomyFileTreeEntry } from "@anatomy-cli/anatomy/core"; import type { AnatomyCheckWithDiagnostics, AnatomyDraftInput } from "@anatomy-cli/schemas"; import { resolve } from "node:path"; -import { DefaultIgnoredNames } from "./DefaultIgnoredNames"; +import { DefaultIgnoredNames } from "./DefaultIgnoredNames.js"; export const formatAgentCheck = ( result: AnatomyCheckResult, @@ -23,8 +23,8 @@ export const formatAgentCheck = ( }; visit(tree, ""); const report: AnatomyCheckWithDiagnostics = { - ...result, contractVersion: 1, operation: "check", - definition: { path: resolve(definitionPath), name: definition.name, schemaVersion: definition.structure.schemaVersion }, + ...result, operation: "check", + definition: { path: resolve(definitionPath), name: definition.name, rootMode: definition.structure.rootMode }, targetPath: resolve(targetPath), fileSelection: gitFiles ? "git" : "filesystem", ignoredNames: gitFiles ? [] : [...new Set([...DefaultIgnoredNames, ...ignore])], diff --git a/apps/anatomy-cli/src/formatAgentError.ts b/apps/anatomy-cli/src/formatAgentError.ts index b1abb2a..b5bf4ec 100644 --- a/apps/anatomy-cli/src/formatAgentError.ts +++ b/apps/anatomy-cli/src/formatAgentError.ts @@ -1,4 +1,4 @@ export const formatAgentError = (error: Error): string => JSON.stringify({ - contractVersion: 1, operation: "error", + operation: "error", error: { code: error.name, message: error.message, ...("path" in error ? { path: error.path } : {}) }, }, null, 2); diff --git a/apps/anatomy-cli/src/formatAgentQuery.ts b/apps/anatomy-cli/src/formatAgentQuery.ts index 69885c0..2701324 100644 --- a/apps/anatomy-cli/src/formatAgentQuery.ts +++ b/apps/anatomy-cli/src/formatAgentQuery.ts @@ -11,7 +11,7 @@ export const formatAgentQuery = ( ): string => { const report = { ...result, - definition: { path: resolve(definitionPath), name: definition.name, schemaVersion: definition.structure.schemaVersion }, + definition: { path: resolve(definitionPath), name: definition.name, rootMode: definition.structure.rootMode }, targetPath: resolve(targetPath), }; if (format === "json") return JSON.stringify(report, null, 2); diff --git a/apps/anatomy-cli/src/function-export-workflow.spec.ts b/apps/anatomy-cli/src/function-export-workflow.spec.ts index c331a48..017a78d 100644 --- a/apps/anatomy-cli/src/function-export-workflow.spec.ts +++ b/apps/anatomy-cli/src/function-export-workflow.spec.ts @@ -2,18 +2,18 @@ import { AnatomyCheckWithDiagnosticsSchema } from "@anatomy-cli/schemas"; import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; import { join, resolve } from "node:path"; import { afterEach, beforeEach, describe, expect, it } from "vitest"; -import { collectSourceExports } from "./collectSourceExports"; -import { collectFileTree } from "./collectFileTree"; -import { findAnatomyDefinition } from "./findAnatomyDefinition"; -import { readAnatomyDefinition } from "./readAnatomyDefinition"; -import { runAnatomyCli } from "./runAnatomyCli"; +import { collectSourceExports } from "./collectSourceExports.js"; +import { collectFileTree } from "./collectFileTree.js"; +import { findAnatomyDefinition } from "./findAnatomyDefinition.js"; +import { readAnatomyDefinition } from "./readAnatomyDefinition.js"; +import { runAnatomyCli } from "./runAnatomyCli.js"; const verificationRoot = resolve(import.meta.dirname, "../../../docs/verification/function-export-tests"); let directory: string; const contract = () => ({ name: "Function modules", purpose: "One function per file", structure: { - schemaVersion: 1, + rootMode: "contents", defaultPolicies: { missingRequired: "block", unexpectedEntry: "block", nameMismatch: "block", nestingMismatch: "block" }, root: { children: [{ kind: "file", name: { type: "placeholder", value: ".ts" }, quantity: "one_or_more", exports: { name: "file_stem" }, @@ -70,7 +70,7 @@ describe("function export CLI workflow", () => { expect(JSON.parse(run.output).issues[0].code).toBe(code); }); - it.each(["export function ( {", "export * from './other';"])("reports unsupported analysis as an operational error: %s", async (source) => { + it.each(["export function ( {", "export * from './other.js';"])("reports unsupported analysis as an operational error: %s", async (source) => { await writeFile(join(directory, "getUser.ts"), source); const run = await invoke(); expect(run.result._unsafeUnwrapErr()).toMatchObject({ name: "AnatomySourceAnalysisError" }); diff --git a/apps/anatomy-cli/src/getPathPlan.ts b/apps/anatomy-cli/src/getPathPlan.ts index 785eff9..ca48cc6 100644 --- a/apps/anatomy-cli/src/getPathPlan.ts +++ b/apps/anatomy-cli/src/getPathPlan.ts @@ -1,6 +1,6 @@ import { existsSync } from "node:fs"; import { basename, join } from "node:path"; -import { quoteShell } from "./quoteShell"; +import { quoteShell } from "./quoteShell.js"; export const getPathPlan = (bin: string, home: string, env: NodeJS.ProcessEnv) => { const shell = basename(env.SHELL ?? "sh"); diff --git a/apps/anatomy-cli/src/git-files.spec.ts b/apps/anatomy-cli/src/git-files.spec.ts index 726bcb6..a4cba7a 100644 --- a/apps/anatomy-cli/src/git-files.spec.ts +++ b/apps/anatomy-cli/src/git-files.spec.ts @@ -2,9 +2,9 @@ import { execFileSync } from "node:child_process"; import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises"; import { resolve } from "node:path"; import { afterEach, describe, expect, it, vi } from "vitest"; -import { collectGitFileTree } from "./collectGitFileTree"; -import { parseCliArguments } from "./parseCliArguments"; -import { runAnatomyCli } from "./runAnatomyCli"; +import { collectGitFileTree } from "./collectGitFileTree.js"; +import { parseCliArguments } from "./parseCliArguments.js"; +import { runAnatomyCli } from "./runAnatomyCli.js"; const temporaryDirectories: string[] = []; const fixture = async () => { @@ -65,7 +65,7 @@ describe("Git file selection", () => { const directory = await fixture(); const definitionPath = resolve(directory, "local/contract.json"); await writeFile(definitionPath, JSON.stringify({ name: "Git fixture", purpose: "No source files allowed", structure: { - schemaVersion: 1, + rootMode: "contents", defaultPolicies: { missingRequired: "block", unexpectedEntry: "block", nameMismatch: "block", nestingMismatch: "block" }, root: { children: [{ kind: "file", name: { type: "literal", value: ".gitignore" }, quantity: "exactly_one" }] }, } })); diff --git a/apps/anatomy-cli/src/index.ts b/apps/anatomy-cli/src/index.ts index cdef334..5b08504 100644 --- a/apps/anatomy-cli/src/index.ts +++ b/apps/anatomy-cli/src/index.ts @@ -1,21 +1,22 @@ -export * from "./analyzeSourceExports"; -export * from "./AnatomyCliArgumentError"; -export * from "./AnatomyCliExitCode"; -export * from "./AnatomyCliFormatValues"; -export * from "./AnatomyCliUsage"; -export * from "./AnatomyDefinitionFileError"; -export * from "./AnatomyFileTreeError"; -export * from "./collectSourceExports"; -export * from "./collectFileTree"; -export * from "./collectGitFileTree"; -export * from "./DefaultAnatomyDefinitionFileName"; -export * from "./DefaultIgnoredNames"; -export * from "./findAnatomyDefinition"; -export * from "./formatAgentCheck"; -export * from "./formatAgentError"; -export * from "./formatAgentQuery"; -export * from "./formatHumanResult"; -export * from "./formatJsonResult"; -export * from "./parseCliArguments"; -export * from "./readAnatomyDefinition"; -export * from "./runAnatomyCli"; +export * from "./analyzeSourceExports.js"; +export * from "./AnatomyCliArgumentError.js"; +export * from "./AnatomyCliExitCode.js"; +export * from "./AnatomyCliFormatValues.js"; +export * from "./AnatomyCliUsage.js"; +export * from "./AnatomyDefinitionFileError.js"; +export * from "./AnatomyFileTreeError.js"; +export * from "./collectSourceExports.js"; +export * from "./collectFileTree.js"; +export * from "./collectGitFileTree.js"; +export * from "./DefaultAnatomyDefinitionFileName.js"; +export * from "./DefaultIgnoredNames.js"; +export * from "./findAnatomyDefinition.js"; +export * from "./formatAgentCheck.js"; +export * from "./formatAgentError.js"; +export * from "./formatAgentQuery.js"; +export * from "./formatHumanResult.js"; +export * from "./formatJsonResult.js"; +export * from "./parseCliArguments.js"; +export * from "./readAnatomyDefinition.js"; +export * from "./runAnatomyCli.js"; +export * from "./runAnatomyBundleCli.js"; diff --git a/apps/anatomy-cli/src/install-main.ts b/apps/anatomy-cli/src/install-main.ts index 65714e1..ed1e704 100644 --- a/apps/anatomy-cli/src/install-main.ts +++ b/apps/anatomy-cli/src/install-main.ts @@ -4,9 +4,9 @@ import { ok } from "neverthrow"; import { homedir } from "node:os"; import { dirname, resolve } from "node:path"; import { fileURLToPath } from "node:url"; -import { installUsage } from "./installUsage"; -import { parseInstallOptions } from "./parseInstallOptions"; -import { runInstallation } from "./runInstallation"; +import { installUsage } from "./installUsage.js"; +import { parseInstallOptions } from "./parseInstallOptions.js"; +import { runInstallation } from "./runInstallation.js"; const result = parseInstallOptions(process.argv.slice(2)).andThen((options) => options.help ? ok([installUsage]) : runInstallation(options, { diff --git a/apps/anatomy-cli/src/install.spec.ts b/apps/anatomy-cli/src/install.spec.ts index 1b66fca..f9ff35f 100644 --- a/apps/anatomy-cli/src/install.spec.ts +++ b/apps/anatomy-cli/src/install.spec.ts @@ -2,12 +2,12 @@ import { execFileSync } from "node:child_process"; import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs"; import { join, resolve } from "node:path"; import { afterEach, beforeEach, describe, expect, it } from "vitest"; -import { getPathPlan } from "./getPathPlan"; -import { parseInstallOptions, type InstallOptions } from "./parseInstallOptions"; -import { quoteShell } from "./quoteShell"; -import { runInstallation, type InstallContext } from "./runInstallation"; -import { windowsLauncher } from "./windowsLauncher"; -import { windowsPathScript } from "./windowsPathScript"; +import { getPathPlan } from "./getPathPlan.js"; +import { parseInstallOptions, type InstallOptions } from "./parseInstallOptions.js"; +import { quoteShell } from "./quoteShell.js"; +import { runInstallation, type InstallContext } from "./runInstallation.js"; +import { windowsLauncher } from "./windowsLauncher.js"; +import { windowsPathScript } from "./windowsPathScript.js"; const projectRoot = resolve(import.meta.dirname, "../../.."); let temporary: string; @@ -25,7 +25,7 @@ beforeEach(() => { writeFileSync(join(packageRoot, "dist", "main.js"), 'console.log(process.argv.includes("--help") ? "Usage: anatomy [target] [options]" : JSON.stringify(process.argv.slice(2)));\n'); options = { prefix: join(home, ".anatomy"), modifyPath: true, uninstall: false, help: false }; context = { - home, packageRoot, platform: "linux", nodeVersion: "22.18.0", nodeExecutable: process.execPath, + home, packageRoot, platform: "linux", nodeVersion: "24.21.0", nodeExecutable: process.execPath, env: { ...process.env, SHELL: "/bin/zsh", ZDOTDIR: "", XDG_CONFIG_HOME: "", ANATOMY_INSTALL_DIR: "" }, }; }); @@ -97,7 +97,9 @@ describe("one-shot installation", () => { expect(readdirSync(options.prefix).some((name) => name.startsWith(".install-"))).toBe(false); }); it("rejects incomplete packages and unsupported runtimes before installation", () => { - expect(runInstallation(options, { ...context, nodeVersion: "16.20.0" }).isErr()).toBe(true); + for (const nodeVersion of ["18.20.8", "22.18.0", "23.11.0"]) { + expect(runInstallation(options, { ...context, nodeVersion })._unsafeUnwrapErr().message).toContain("Node.js 24"); + } expect(existsSync(options.prefix)).toBe(false); rmSync(join(context.packageRoot, "dist", "main.js")); expect(runInstallation(options, context).isErr()).toBe(true); diff --git a/apps/anatomy-cli/src/installUsage.ts b/apps/anatomy-cli/src/installUsage.ts index 2bc6bbb..ad422bd 100644 --- a/apps/anatomy-cli/src/installUsage.ts +++ b/apps/anatomy-cli/src/installUsage.ts @@ -4,7 +4,7 @@ export const installUsage = `Install Anatomy once, then run: anatomy ./src pnpm: pnpm dlx anatomy-cli Bun: bunx anatomy-cli -Requires Node.js 18+. No administrator privileges or project changes. +Requires Node.js 24+. No administrator privileges or project changes. Downloads are handled by your package manager; the installer copies this release. Options: diff --git a/apps/anatomy-cli/src/main.ts b/apps/anatomy-cli/src/main.ts index fe01cb0..6bf26a7 100755 --- a/apps/anatomy-cli/src/main.ts +++ b/apps/anatomy-cli/src/main.ts @@ -1,9 +1,9 @@ #!/usr/bin/env node -import { AnatomyCliExitCode } from "./AnatomyCliExitCode"; -import { AnatomyCliUsage } from "./AnatomyCliUsage"; -import { formatAgentError } from "./formatAgentError"; -import { runAnatomyCli } from "./runAnatomyCli"; +import { AnatomyCliExitCode } from "./AnatomyCliExitCode.js"; +import { AnatomyCliUsage } from "./AnatomyCliUsage.js"; +import { formatAgentError } from "./formatAgentError.js"; +import { runAnatomyCli } from "./runAnatomyCli.js"; const result = await runAnatomyCli(process.argv.slice(2)); diff --git a/apps/anatomy-cli/src/packed-consumer.spec.ts b/apps/anatomy-cli/src/packed-consumer.spec.ts new file mode 100644 index 0000000..2e3e2bb --- /dev/null +++ b/apps/anatomy-cli/src/packed-consumer.spec.ts @@ -0,0 +1,297 @@ +import { existsSync } from "node:fs"; +import { execFile } from "node:child_process"; +import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises"; +import { resolve, join } from "node:path"; +import { promisify } from "node:util"; +import { ResultAsync } from "neverthrow"; +import { beforeAll, describe, expect, it } from "vitest"; + +const root = resolve(import.meta.dirname, "../../.."); +const execute = (command: string, args: string[], cwd: string) => + ResultAsync.fromPromise( + promisify(execFile)(command, args, { cwd, maxBuffer: 8 * 1024 * 1024 }), + (cause) => cause, + ); +let consumer: string; +let bundlePath: string; +let targetPath: string; +let cliPath: string; + +beforeAll(async () => { + await mkdir(join(root, "docs/verification/cod-420"), { recursive: true }); + consumer = await mkdtemp(join(root, "docs/verification/cod-420/consumer-")); + (await execute("bun", ["run", "build"], root))._unsafeUnwrap(); + const tarballs: string[] = []; + for (const pkg of [ + "packages/schemas", + "packages/anatomy", + "apps/anatomy-cli", + ]) { + const packed = ( + await execute( + "npm", + ["pack", "--ignore-scripts", "--json", "--pack-destination", consumer], + join(root, pkg), + ) + )._unsafeUnwrap(); + tarballs.push(join(consumer, JSON.parse(packed.stdout)[0].filename)); + } + await writeFile( + join(consumer, "package.json"), + JSON.stringify({ + name: "anatomy-isolated-consumer", + private: true, + type: "module", + }), + ); + ( + await execute( + "npm", + ["install", "--ignore-scripts", "--no-audit", "--no-fund", ...tarballs], + consumer, + ) + )._unsafeUnwrap(); + bundlePath = join(consumer, "bundle.json"); + await writeFile( + bundlePath, + await readFile( + join(root, "apps/anatomy-cli/anatomies/db-schema.bundle.json"), + ), + ); + targetPath = join(consumer, "db-schema"); + for (const path of [ + "package.json", + "tsconfig.json", + "src/index.ts", + "src/tables/index.ts", + "src/tables/accounts/index.ts", + "src/tables/accounts/accounts.table.ts", + "src/relations/index.ts", + ]) { + const file = join(targetPath, path); + await mkdir(resolve(file, ".."), { recursive: true }); + await writeFile(file, ""); + } + cliPath = join(consumer, "node_modules/anatomy-cli/bin/anatomy.js"); + await writeFile( + join(consumer, "sdk.mjs"), + `import {scanAnatomy} from '@anatomy-cli/anatomy'; +import {AnatomyScanOutcomeSchema} from '@anatomy-cli/schemas'; +import {readFileSync} from 'node:fs';import {createRequire} from 'node:module'; +const require=createRequire(import.meta.url); +for(const name of ['@anatomy-cli/anatomy','@anatomy-cli/schemas','typescript']) { + if(!require.resolve(name).startsWith(process.cwd()+'/node_modules/')) throw Error('dependency escaped consumer: '+name); +} +if(Number(process.versions.node.split('.')[0]) < 24) throw Error('Node 24+ required'); +if(Object.keys(require.cache).some(p=>p.includes('/typescript/'))) throw Error('eager TypeScript load'); +const file=name=>({kind:'file',name}); const dir=(name,children)=>({kind:'directory',name,children}); +const target=dir('db-schema',[file('package.json'),file('tsconfig.json'),dir('src',[file('index.ts'),dir('tables',[file('index.ts'),dir('accounts',[file('index.ts'),file('accounts.table.ts')])]),dir('relations',[file('index.ts')])])]); +if(process.argv.includes('--violation')) target.children.push(file('extra.ts')); +const bundle=JSON.parse(readFileSync('bundle.json','utf8')); +let sources; +if(process.argv.includes('--source')) { + bundle.root='table-domain'; + bundle.definitions.find(item=>item.key===bundle.root).definition.structure.root.children=[{kind:'file',name:{type:'literal',value:'getUser.ts'},quantity:'exactly_one',exports:{name:'file_stem',policy:'block'}}]; + target.name='accounts'; target.children=[file('getUser.ts')]; + sources={'getUser.ts':'export function getUser() { return 1; }'}; +} +const result=await scanAnatomy({bundle,target,sources,coverage:{status:'complete'}}); +AnatomyScanOutcomeSchema.parse(result);console.log(JSON.stringify(result));`, + ); +}, 120_000); + +describe("isolated packed Node consumer", () => { + /** @summary Install packages in an ordinary Node consumer + * @description + * Given: An isolated consumer uses installed tarballs and runs exclusively through Node. + * When: The maintainer installs and runs the packed consumer example. + * Then: ESM imports, type resolution, and CLI bins work without unresolved workspace dependencies. + */ + it("[AC-28] resolves JavaScript, declarations and manifests", async () => { + for (const pkg of [ + "@anatomy-cli/schemas", + "@anatomy-cli/anatomy", + "anatomy-cli", + ]) { + const manifest = await readFile( + join(consumer, "node_modules", pkg, "package.json"), + "utf8", + ); + expect(manifest).not.toContain("workspace:"); + expect(JSON.parse(manifest).engines.node).toBe(">=24"); + } + await writeFile( + join(consumer, "typecheck.ts"), + `import {scanAnatomy,queryAnatomyBundle,validateAnatomyBundle} from '@anatomy-cli/anatomy'; +import type {AnatomyScanOutcome,AnatomyBundleQueryOutcome} from '@anatomy-cli/schemas'; +import {parseCliArguments} from 'anatomy-cli'; +parseCliArguments(['.', '--bundle', 'bundle.json']); +const scan: Promise = scanAnatomy({}); +const query: AnatomyBundleQueryOutcome = queryAnatomyBundle({}); +validateAnatomyBundle({}); void scan; void query;`, + ); + for (const obsolete of [ + "AnatomyVersionSchema", + "AnatomyPublishedVersionListInputSchema", + ]) { + expect( + existsSync( + join( + consumer, + "node_modules/@anatomy-cli/schemas/dist/anatomy", + `${obsolete}.js`, + ), + ), + ).toBe(false); + } + expect( + existsSync( + join( + consumer, + "node_modules/@anatomy-cli/schemas/dist/composition/AnatomyNodeV2Schema.js", + ), + ), + ).toBe(false); + const tsc = join(consumer, "node_modules/typescript/bin/tsc"); + expect( + ( + await execute( + process.execPath, + [ + tsc, + "--noEmit", + "--strict", + "--skipLibCheck", + "--target", + "ES2022", + "--module", + "NodeNext", + "--moduleResolution", + "NodeNext", + "typecheck.ts", + ], + consumer, + ) + ).isOk(), + ).toBe(true); + const cli = await execute(process.execPath, [cliPath, "--help"], consumer); + expect(cli._unsafeUnwrap().stdout).toContain("--bundle"); + }); + /** @summary Scan five definitions from supplied data alone + * @description + * Given: A product-side fixture maps five authorized definitions to logical keys and supplies the complete target tree. + * When: The integrator runs the packed SDK consumer example. + * Then: The result has actual mount provenance without temporary directories, network reads, or a second scanner. + */ + it("[AC-30] imports a lazy data-only SDK in Node", async () => { + const result = ( + await execute(process.execPath, ["sdk.mjs"], consumer) + )._unsafeUnwrap(); + expect(JSON.parse(result.stdout)).toMatchObject({ + status: "completed", + conforms: true, + }); + const source = ( + await execute(process.execPath, ["sdk.mjs", "--source"], consumer) + )._unsafeUnwrap(); + expect(JSON.parse(source.stdout)).toMatchObject({ + status: "completed", + conforms: true, + }); + }); + /** @summary Keep CLI and SDK outcomes equivalent + * @description + * Given: CLI and SDK receive identical definitions, target trees, and sources. + * When: The maintainer runs the two scan entry points for comparison. + * Then: Finding codes, severities, relative paths, origins, and mount chains agree. + */ + it("[AC-25] agrees between installed CLI and SDK", async () => { + const sdk = ( + await execute(process.execPath, ["sdk.mjs"], consumer) + )._unsafeUnwrap(); + const cli = ( + await execute( + process.execPath, + [cliPath, targetPath, "--bundle", bundlePath, "--format", "json"], + consumer, + ) + )._unsafeUnwrap(); + expect(JSON.parse(cli.stdout)).toEqual(JSON.parse(sdk.stdout)); + const query = ( + await execute( + process.execPath, + [ + cliPath, + targetPath, + "--bundle", + bundlePath, + "--query", + "src/tables/accounts", + "--format", + "json", + ], + consumer, + ) + )._unsafeUnwrap(); + expect(JSON.parse(query.stdout)).toMatchObject({ + status: "resolved", + rules: [ + { origin: { definitionKey: "tables-class" } }, + { origin: { definitionKey: "table-domain" } }, + ], + }); + }); + /** @summary Distinguish pass, block, and execution error in CLI exit codes + * @description + * Given: Fixtures respectively conform, contain a block finding, and have an unavailable reference. + * When: The maintainer runs anatomy --bundle for each fixture. + * Then: Exit codes are respectively 0, 1, and 2 with consistent JSON completion states. + */ + it("[AC-26] distinguishes exit codes and preserves unexpected files", async () => { + await writeFile(join(targetPath, "extra.ts"), "must remain"); + const blocked = await execute( + process.execPath, + [cliPath, targetPath, "--bundle", bundlePath, "--format", "json"], + consumer, + ); + expect(blocked.isErr()).toBe(true); + if (blocked.isErr()) { + const error = blocked.error as { code: number; stdout: string }; + expect(error.code).toBe(1); + expect(JSON.parse(error.stdout)).toMatchObject({ + status: "completed", + conforms: false, + issues: [{ code: "unexpected_entry" }], + }); + } + const sdk = ( + await execute(process.execPath, ["sdk.mjs", "--violation"], consumer) + )._unsafeUnwrap(); + if (blocked.isErr()) { + expect(JSON.parse((blocked.error as { stdout: string }).stdout)).toEqual( + JSON.parse(sdk.stdout), + ); + } + expect(await readFile(join(targetPath, "extra.ts"), "utf8")).toBe( + "must remain", + ); + const bundle = JSON.parse(await readFile(bundlePath, "utf8")); + bundle.root = "missing"; + const bad = join(consumer, "invalid.json"); + await writeFile(bad, JSON.stringify(bundle)); + const failed = await execute( + process.execPath, + [cliPath, targetPath, "--bundle", bad, "--format", "json"], + consumer, + ); + expect(failed.isErr()).toBe(true); + if (failed.isErr()) { + const error = failed.error as { code: number; stdout: string }; + expect(error.code).toBe(2); + expect(JSON.parse(error.stdout)).toMatchObject({ + status: "error", + conforms: null, + }); + } + }); +}); diff --git a/apps/anatomy-cli/src/parseCliArguments.ts b/apps/anatomy-cli/src/parseCliArguments.ts index 8977d4a..8d78ba0 100644 --- a/apps/anatomy-cli/src/parseCliArguments.ts +++ b/apps/anatomy-cli/src/parseCliArguments.ts @@ -1,9 +1,10 @@ import { err, ok, type Result } from "neverthrow"; -import { AnatomyCliArgumentError } from "./AnatomyCliArgumentError"; -import { AnatomyCliFormatValues } from "./AnatomyCliFormatValues"; +import { AnatomyCliArgumentError } from "./AnatomyCliArgumentError.js"; +import { AnatomyCliFormatValues } from "./AnatomyCliFormatValues.js"; export type AnatomyCliOptions = { definitionPath: string | null; + bundlePath: string | null; targetPath: string; format: (typeof AnatomyCliFormatValues)[number]; ignore: string[]; @@ -29,6 +30,7 @@ export const parseCliArguments = ( ): Result => { const options: AnatomyCliOptions = { definitionPath: null, + bundlePath: null, targetPath: ".", format: "human", ignore: [], @@ -61,8 +63,23 @@ export const parseCliArguments = ( continue; } + if (argument === "--bundle") { + if (options.bundlePath !== null) + return err( + new AnatomyCliArgumentError("Bundle may only be specified once"), + ); + const value = getOptionValue(args, index, argument); + if (value.isErr()) return err(value.error); + options.bundlePath = value.value; + consumedIndexes.add(index + 1); + continue; + } + if (argument === "--query") { - if (options.queryPath !== null) return err(new AnatomyCliArgumentError("Query path may only be specified once")); + if (options.queryPath !== null) + return err( + new AnatomyCliArgumentError("Query path may only be specified once"), + ); const value = getOptionValue(args, index, argument); if (value.isErr()) return err(value.error); options.queryPath = value.value; @@ -72,7 +89,11 @@ export const parseCliArguments = ( if (argument === "--target" || argument === "-t") { if (targetSpecified) { - return err(new AnatomyCliArgumentError("Target directory may only be specified once")); + return err( + new AnatomyCliArgumentError( + "Target directory may only be specified once", + ), + ); } const value = getOptionValue(args, index, argument); if (value.isErr()) return err(value.error); @@ -85,7 +106,11 @@ export const parseCliArguments = ( if (argument === "--format") { const value = getOptionValue(args, index, argument); if (value.isErr()) return err(value.error); - if (!AnatomyCliFormatValues.includes(value.value as AnatomyCliOptions["format"])) { + if ( + !AnatomyCliFormatValues.includes( + value.value as AnatomyCliOptions["format"], + ) + ) { return err( new AnatomyCliArgumentError( `Unsupported format "${value.value}"; expected human or json`, @@ -120,10 +145,30 @@ export const parseCliArguments = ( } if (options.queryPath !== null && options.ignore.length > 0) { - return err(new AnatomyCliArgumentError("--ignore is only supported for checks; queries describe declared constraints")); + return err( + new AnatomyCliArgumentError( + "--ignore is only supported for checks; queries describe declared constraints", + ), + ); } if (options.gitFiles && options.ignore.length > 0) { - return err(new AnatomyCliArgumentError("--git-files cannot be combined with --ignore")); + return err( + new AnatomyCliArgumentError( + "--git-files cannot be combined with --ignore", + ), + ); } + if (options.bundlePath !== null && options.definitionPath !== null) + return err( + new AnatomyCliArgumentError( + "--bundle and --definition are mutually exclusive", + ), + ); + if (options.bundlePath !== null && options.ignore.length > 0) + return err( + new AnatomyCliArgumentError( + "--bundle requires a complete tree and cannot be combined with --ignore", + ), + ); return ok(options); }; diff --git a/apps/anatomy-cli/src/parseInstallOptions.ts b/apps/anatomy-cli/src/parseInstallOptions.ts index 9e9cc42..74e9349 100644 --- a/apps/anatomy-cli/src/parseInstallOptions.ts +++ b/apps/anatomy-cli/src/parseInstallOptions.ts @@ -1,7 +1,7 @@ import { err, ok, type Result } from "neverthrow"; import { homedir } from "node:os"; import { isAbsolute, join, parse, resolve } from "node:path"; -import { AnatomyInstallError } from "./AnatomyInstallError"; +import { AnatomyInstallError } from "./AnatomyInstallError.js"; export type InstallOptions = { prefix: string; diff --git a/apps/anatomy-cli/src/readAnatomyDefinition.ts b/apps/anatomy-cli/src/readAnatomyDefinition.ts index 9237a53..c0b28c9 100644 --- a/apps/anatomy-cli/src/readAnatomyDefinition.ts +++ b/apps/anatomy-cli/src/readAnatomyDefinition.ts @@ -2,7 +2,7 @@ import { AnatomyDraftInputSchema, type AnatomyDraftInput } from "@anatomy-cli/sc import { err, ok, Result, ResultAsync } from "neverthrow"; import { readFile } from "node:fs/promises"; import { resolve } from "node:path"; -import { AnatomyDefinitionFileError } from "./AnatomyDefinitionFileError"; +import { AnatomyDefinitionFileError } from "./AnatomyDefinitionFileError.js"; const parseJson = Result.fromThrowable( JSON.parse, diff --git a/apps/anatomy-cli/src/repository-contract.spec.ts b/apps/anatomy-cli/src/repository-contract.spec.ts index cbf3b17..472a7bf 100644 --- a/apps/anatomy-cli/src/repository-contract.spec.ts +++ b/apps/anatomy-cli/src/repository-contract.spec.ts @@ -3,9 +3,9 @@ import { basename, dirname, resolve } from "node:path"; import ts from "typescript"; import { describe, expect, it } from "vitest"; import { anatomyRulePaths, checkAnatomy, planAnatomyCheck, type AnatomyFileTreeEntry } from "@anatomy-cli/anatomy/core"; -import { collectGitFileTree } from "./collectGitFileTree"; -import { collectSourceExports } from "./collectSourceExports"; -import { readAnatomyDefinition } from "./readAnatomyDefinition"; +import { collectGitFileTree } from "./collectGitFileTree.js"; +import { collectSourceExports } from "./collectSourceExports.js"; +import { readAnatomyDefinition } from "./readAnatomyDefinition.js"; const root = resolve(import.meta.dirname, "../../.."); const load = async () => { diff --git a/apps/anatomy-cli/src/runAnatomyBundleCli.ts b/apps/anatomy-cli/src/runAnatomyBundleCli.ts new file mode 100644 index 0000000..1f9f561 --- /dev/null +++ b/apps/anatomy-cli/src/runAnatomyBundleCli.ts @@ -0,0 +1,126 @@ +import { readFile } from "node:fs/promises"; +import { basename, resolve } from "node:path"; +import { Result, ResultAsync, ok } from "neverthrow"; +import { + planAnatomyBundle, + scanAnatomy, + queryAnatomyBundle, +} from "@anatomy-cli/anatomy"; +import type { + AnatomyDiagnostic, + AnatomyScanOutcome, + AnatomyBundleQueryOutcome, +} from "@anatomy-cli/schemas"; +import type { AnatomyCliOptions } from "./parseCliArguments.js"; +import type { AnatomyCliDependencies } from "./runAnatomyCli.js"; +import { collectGitFileTree } from "./collectGitFileTree.js"; + +export const runAnatomyBundleCli = async ( + options: AnatomyCliOptions, + dependencies: AnatomyCliDependencies, +) => { + const emit = (result: AnatomyScanOutcome | AnatomyBundleQueryOutcome) => { + if (options.format === "json") + dependencies.writeOutput(JSON.stringify(result, null, 2)); + else if (result.status === "error") + dependencies.writeOutput( + result.diagnostics + .map((d) => `ERROR ${d.code}: ${d.message}`) + .join("\n"), + ); + else if (result.operation === "query") + dependencies.writeOutput(JSON.stringify(result, null, 2)); + else + dependencies.writeOutput( + [ + result.conforms + ? "Anatomy structure conforms" + : "Anatomy structure does not conform", + ...result.issues.map( + (i) => + `${i.severity.toUpperCase()} ${i.code} ${i.entryPath} [${i.origin.definitionKey}${i.origin.rulePath}]: ${i.message}`, + ), + `block: ${result.summary.block}, warn: ${result.summary.warn}, allow: ${result.summary.allow}`, + ].join("\n"), + ); + return ok( + result.status === "error" + ? 2 + : result.operation === "check" && !result.conforms + ? 1 + : 0, + ); + }; + const fail = (diagnostic: AnatomyDiagnostic) => + emit( + options.queryPath === null + ? { + operation: "check", + status: "error", + conforms: null, + diagnostics: [diagnostic], + } + : { + operation: "query", + status: "error", + diagnostics: [diagnostic], + }, + ); + const raw = await ResultAsync.fromPromise( + readFile(resolve(options.bundlePath!), "utf8"), + () => ({ + code: "invalid_bundle" as const, + message: "Unable to read bundle file", + }), + ); + if (raw.isErr()) return fail(raw.error); + const bundle = Result.fromThrowable( + (text: string): unknown => JSON.parse(text), + () => ({ code: "invalid_bundle" as const, message: "Invalid bundle JSON" }), + )(raw.value); + if (bundle.isErr()) return fail(bundle.error); + const name = basename(resolve(options.targetPath)); + if (options.queryPath !== null) + return emit( + queryAnatomyBundle({ + bundle: bundle.value, + path: options.queryPath, + targetName: name, + }), + ); + const collected = options.gitFiles + ? await (dependencies.collectGitTree ?? collectGitFileTree)( + options.targetPath, + ) + : await dependencies.collectTree(options.targetPath, options.ignore); + if (collected.isErr()) + return fail({ code: "invalid_tree", message: collected.error.message }); + const input = { + bundle: bundle.value, + target: { name, kind: "directory" as const, children: collected.value }, + coverage: { status: "complete" as const }, + }; + const plan = planAnatomyBundle(input); + if (plan.isErr()) + return emit({ + operation: "check", + status: "error", + conforms: null, + diagnostics: plan.error, + }); + const sources: Record = {}; + for (const { check } of plan.value.exports) { + if (Object.hasOwn(sources, check.path)) continue; + const source = await ResultAsync.fromPromise( + readFile(resolve(options.targetPath, check.path), "utf8"), + () => ({ + code: "source_unavailable" as const, + message: "Unable to read required source", + entryPath: check.path, + }), + ); + if (source.isErr()) return fail(source.error); + sources[check.path] = source.value; + } + return emit(await scanAnatomy({ ...input, sources })); +}; diff --git a/apps/anatomy-cli/src/runAnatomyCli.ts b/apps/anatomy-cli/src/runAnatomyCli.ts index 3aab14e..f90f79a 100644 --- a/apps/anatomy-cli/src/runAnatomyCli.ts +++ b/apps/anatomy-cli/src/runAnatomyCli.ts @@ -1,27 +1,36 @@ -import { checkAnatomy, planAnatomyCheck, queryAnatomy, type AnatomyFileTreeEntry } from "@anatomy-cli/anatomy/core"; +import { runAnatomyBundleCli } from "./runAnatomyBundleCli.js"; +import { + checkAnatomy, + planAnatomyCheck, + queryAnatomy, + type AnatomyFileTreeEntry, +} from "@anatomy-cli/anatomy/core"; import type { AnatomyDraftInput } from "@anatomy-cli/schemas"; import { err, ok, type Result } from "neverthrow"; -import { AnatomyCliExitCode } from "./AnatomyCliExitCode"; -import { AnatomyCliUsage } from "./AnatomyCliUsage"; -import { AnatomyDefinitionFileError } from "./AnatomyDefinitionFileError"; -import { type AnatomyFileTreeError } from "./AnatomyFileTreeError"; -import { collectSourceExports } from "./collectSourceExports"; -import { collectFileTree } from "./collectFileTree"; -import { collectGitFileTree } from "./collectGitFileTree"; -import { findAnatomyDefinition } from "./findAnatomyDefinition"; -import { formatAgentCheck } from "./formatAgentCheck"; -import { formatAgentQuery } from "./formatAgentQuery"; -import { formatHumanResult } from "./formatHumanResult"; -import { parseCliArguments, type AnatomyCliOptions } from "./parseCliArguments"; -import { readAnatomyDefinition } from "./readAnatomyDefinition"; +import { AnatomyCliExitCode } from "./AnatomyCliExitCode.js"; +import { AnatomyCliUsage } from "./AnatomyCliUsage.js"; +import { AnatomyDefinitionFileError } from "./AnatomyDefinitionFileError.js"; +import { type AnatomyFileTreeError } from "./AnatomyFileTreeError.js"; +import { collectSourceExports } from "./collectSourceExports.js"; +import { collectFileTree } from "./collectFileTree.js"; +import { collectGitFileTree } from "./collectGitFileTree.js"; +import { findAnatomyDefinition } from "./findAnatomyDefinition.js"; +import { formatAgentCheck } from "./formatAgentCheck.js"; +import { formatAgentQuery } from "./formatAgentQuery.js"; +import { formatHumanResult } from "./formatHumanResult.js"; +import { parseCliArguments, type AnatomyCliOptions } from "./parseCliArguments.js"; +import { readAnatomyDefinition } from "./readAnatomyDefinition.js"; -export type AnatomyCliError = Error | AnatomyDefinitionFileError | AnatomyFileTreeError; +export type AnatomyCliError = + Error | AnatomyDefinitionFileError | AnatomyFileTreeError; export type AnatomyCliDependencies = { findDefinition: ( targetPath: string, ) => Promise>; - readDefinition: (path: string) => Promise>; + readDefinition: ( + path: string, + ) => Promise>; collectTree: ( targetPath: string, ignoredNames: string[], @@ -52,6 +61,9 @@ export const runAnatomyCli = async ( return ok(AnatomyCliExitCode.success); } + if (options.bundlePath !== null) + return runAnatomyBundleCli(options, dependencies); + const definitionPath = options.definitionPath ? ok(options.definitionPath) : await dependencies.findDefinition(options.targetPath); @@ -61,28 +73,53 @@ export const runAnatomyCli = async ( if (definition.isErr()) return err(definition.error); const tree = options.gitFiles - ? await (dependencies.collectGitTree ?? collectGitFileTree)(options.targetPath) + ? await (dependencies.collectGitTree ?? collectGitFileTree)( + options.targetPath, + ) : await dependencies.collectTree(options.targetPath, options.ignore); if (tree.isErr()) return err(tree.error); if (options.queryPath !== null) { const queried = queryAnatomy(definition.value, options.queryPath); if (queried.isErr()) { - return err(Array.isArray(queried.error) - ? new AnatomyDefinitionFileError(queried.error.map((issue) => issue.message).join("; "), definitionPath.value) - : queried.error); + return err( + Array.isArray(queried.error) + ? new AnatomyDefinitionFileError( + queried.error.map((issue) => issue.message).join("; "), + definitionPath.value, + ) + : queried.error, + ); } - dependencies.writeOutput(formatAgentQuery(queried.value, definition.value, - definitionPath.value, options.targetPath, options.format)); + dependencies.writeOutput( + formatAgentQuery( + queried.value, + definition.value, + definitionPath.value, + options.targetPath, + options.format, + ), + ); return ok(AnatomyCliExitCode.success); } const plan = planAnatomyCheck(definition.value, tree.value); - if (plan.isErr()) return err(new AnatomyDefinitionFileError( - plan.error.map((issue) => issue.message).join("; "), definitionPath.value)); - const sourceExports = await (dependencies.collectExports ?? collectSourceExports)(options.targetPath, plan.value.exportChecks); + if (plan.isErr()) + return err( + new AnatomyDefinitionFileError( + plan.error.map((issue) => issue.message).join("; "), + definitionPath.value, + ), + ); + const sourceExports = await ( + dependencies.collectExports ?? collectSourceExports + )(options.targetPath, plan.value.exportChecks); if (sourceExports.isErr()) return err(sourceExports.error); - const checked = checkAnatomy(definition.value, tree.value, sourceExports.value); + const checked = checkAnatomy( + definition.value, + tree.value, + sourceExports.value, + ); if (checked.isErr()) { if (!Array.isArray(checked.error)) return err(checked.error); return err( @@ -94,9 +131,22 @@ export const runAnatomyCli = async ( } dependencies.writeOutput( - options.format === "json" ? formatAgentCheck(checked.value, definition.value, - definitionPath.value, options.targetPath, tree.value, options.ignore, options.gitFiles) : formatHumanResult(checked.value), + options.format === "json" + ? formatAgentCheck( + checked.value, + definition.value, + definitionPath.value, + options.targetPath, + tree.value, + options.ignore, + options.gitFiles, + ) + : formatHumanResult(checked.value), ); - return ok(checked.value.conforms ? AnatomyCliExitCode.success : AnatomyCliExitCode.blocked); + return ok( + checked.value.conforms + ? AnatomyCliExitCode.success + : AnatomyCliExitCode.blocked, + ); }; diff --git a/apps/anatomy-cli/src/runInstallation.ts b/apps/anatomy-cli/src/runInstallation.ts index 1122b24..9b3d9a4 100644 --- a/apps/anatomy-cli/src/runInstallation.ts +++ b/apps/anatomy-cli/src/runInstallation.ts @@ -2,12 +2,12 @@ import { err, ok, Result } from "neverthrow"; import { spawnSync } from "node:child_process"; import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"; import { join } from "node:path"; -import { AnatomyInstallError } from "./AnatomyInstallError"; -import { configurePath } from "./configurePath"; -import { getPathPlan } from "./getPathPlan"; -import { type InstallOptions } from "./parseInstallOptions"; -import { posixLauncher } from "./posixLauncher"; -import { windowsLauncher } from "./windowsLauncher"; +import { AnatomyInstallError } from "./AnatomyInstallError.js"; +import { configurePath } from "./configurePath.js"; +import { getPathPlan } from "./getPathPlan.js"; +import { type InstallOptions } from "./parseInstallOptions.js"; +import { posixLauncher } from "./posixLauncher.js"; +import { windowsLauncher } from "./windowsLauncher.js"; const markerName = "install.json"; @@ -26,7 +26,7 @@ export const runInstallation = ( options: InstallOptions, context: InstallContext, ): Result => { - if (Number(context.nodeVersion.split(".")[0]) < 18) return err(new AnatomyInstallError("Anatomy requires Node.js 18 or newer.")); + if (Number(context.nodeVersion.split(".")[0]) < 24) return err(new AnatomyInstallError("Anatomy requires Node.js 24 or newer.")); if (!["darwin", "linux", "win32"].includes(context.platform)) return err(new AnatomyInstallError(`Unsupported platform: ${context.platform}`)); const prefix = options.prefix; const bin = join(prefix, "bin"); diff --git a/apps/anatomy-cli/src/source-contract.spec.ts b/apps/anatomy-cli/src/source-contract.spec.ts index 66f08d1..369f0ef 100644 --- a/apps/anatomy-cli/src/source-contract.spec.ts +++ b/apps/anatomy-cli/src/source-contract.spec.ts @@ -1,9 +1,9 @@ import { checkAnatomy, planAnatomyCheck } from "@anatomy-cli/anatomy/core"; import { resolve } from "node:path"; import { describe, expect, it } from "vitest"; -import { collectSourceExports } from "./collectSourceExports"; -import { collectFileTree } from "./collectFileTree"; -import { readAnatomyDefinition } from "./readAnatomyDefinition"; +import { collectSourceExports } from "./collectSourceExports.js"; +import { collectFileTree } from "./collectFileTree.js"; +import { readAnatomyDefinition } from "./readAnatomyDefinition.js"; describe("CLI source contract", () => { it("checks the real source directory against the shipped example definition", async () => { diff --git a/apps/anatomy-cli/tsconfig.build.json b/apps/anatomy-cli/tsconfig.build.json new file mode 100644 index 0000000..e01fb56 --- /dev/null +++ b/apps/anatomy-cli/tsconfig.build.json @@ -0,0 +1,18 @@ +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "noEmit": false, + "declaration": true, + "declarationMap": false, + "rootDir": "src", + "outDir": "dist", + "paths": {}, + "emitDeclarationOnly": true + }, + "include": [ + "src" + ], + "exclude": [ + "src/**/*.spec.ts" + ] +} diff --git a/apps/anatomy-cli/tsconfig.json b/apps/anatomy-cli/tsconfig.json index 63586b9..cf45886 100644 --- a/apps/anatomy-cli/tsconfig.json +++ b/apps/anatomy-cli/tsconfig.json @@ -11,7 +11,12 @@ "resolveJsonModule": true, "isolatedModules": true, "noEmit": true, - "types": ["node"] + "types": [ + "node" + ] }, - "include": ["src"] + "include": [ + "src" + ], + "extends": "../../tsconfig.json" } diff --git a/apps/docs/package.json b/apps/docs/package.json index 31e68a1..ceaf004 100644 --- a/apps/docs/package.json +++ b/apps/docs/package.json @@ -60,5 +60,8 @@ "vite": "^8.0.0", "vitest": "4.1.10", "wrangler": "4.129.0" + }, + "engines": { + "node": ">=24" } } diff --git a/apps/docs/plans/2026-09-01-placeholder-binding-design.md b/apps/docs/plans/2026-09-01-placeholder-binding-design.md index e14fcbb..688b6ef 100644 --- a/apps/docs/plans/2026-09-01-placeholder-binding-design.md +++ b/apps/docs/plans/2026-09-01-placeholder-binding-design.md @@ -9,12 +9,12 @@ be able to say that `Name` is PascalCase and that every descendant using ## JSON shape -Bindings are declared next to `schemaVersion` and `defaultPolicies`: +Bindings are declared next to `rootMode` and `defaultPolicies`: ```json { "structure": { - "schemaVersion": 1, + "rootMode": "contents", "bindings": { "Name": { "format": "PascalCase", @@ -57,4 +57,4 @@ attempt to infer acronyms or split words beyond these documented conventions. Add schema tests for binding parsing and invalid patterns; checker tests for each built-in format, combined format-plus-pattern constraints, captured-value consistency, independent repeated-directory scopes, and compatibility with -legacy definitions that do not declare bindings. +definitions that do not declare bindings. diff --git a/apps/docs/src/docsEntries.ts b/apps/docs/src/docsEntries.ts index ec61678..adbf6c9 100644 --- a/apps/docs/src/docsEntries.ts +++ b/apps/docs/src/docsEntries.ts @@ -27,7 +27,7 @@ export const docsEntries: DocsEntry[] = [ { type: "code", language: "bash", code: "pnpm dlx anatomy-cli@latest" }, { type: "heading", text: "卸载" }, { type: "code", language: "bash", code: "pnpm dlx anatomy-cli --uninstall" }, - { type: "paragraph", text: "需要 Node.js 18+。默认安装到 ~/.anatomy,并配置终端 PATH;完成后打开新终端。仓库仍需提供 anatomy.json。可用 --prefix 指定绝对路径,或用 --no-modify-path 自行管理 PATH。卸载保留终端配置及其备份,可手动移除 Anatomy PATH 条目。" }, + { type: "paragraph", text: "需要 Node.js 24+。默认安装到 ~/.anatomy,并配置终端 PATH;完成后打开新终端。仓库仍需提供 anatomy.json。可用 --prefix 指定绝对路径,或用 --no-modify-path 自行管理 PATH。卸载保留终端配置及其备份,可手动移除 Anatomy PATH 条目。" }, ], }, { diff --git a/apps/docs/src/locales/en.json b/apps/docs/src/locales/en.json index c61ea7f..0e65e78 100644 --- a/apps/docs/src/locales/en.json +++ b/apps/docs/src/locales/en.json @@ -212,7 +212,7 @@ "3": "Start using Anatomy", "5": "Upgrade", "7": "Uninstall", - "9": "Requires Node.js 18+. Installs into ~/.anatomy and configures your terminal PATH; open a new terminal afterwards. Your repository still needs anatomy.json. Use --prefix with an absolute path for a custom directory, or --no-modify-path to manage PATH yourself. Uninstall keeps shell settings and backups; remove the Anatomy PATH entry manually if desired." + "9": "Requires Node.js 24+. Installs into ~/.anatomy and configures your terminal PATH; open a new terminal afterwards. Your repository still needs anatomy.json. Use --prefix with an absolute path for a custom directory, or --no-modify-path to manage PATH yourself. Uninstall keeps shell settings and backups; remove the Anatomy PATH entry manually if desired." } }, "quick-start": { diff --git a/apps/docs/src/locales/zh.json b/apps/docs/src/locales/zh.json index c9cac62..719ff9a 100644 --- a/apps/docs/src/locales/zh.json +++ b/apps/docs/src/locales/zh.json @@ -212,7 +212,7 @@ "3": "开始使用", "5": "升级", "7": "卸载", - "9": "需要 Node.js 18+。默认安装到 ~/.anatomy,并配置终端 PATH;完成后打开新终端。仓库仍需提供 anatomy.json。可用 --prefix 指定绝对路径,或用 --no-modify-path 自行管理 PATH。卸载保留终端配置及其备份,可手动移除 Anatomy PATH 条目。" + "9": "需要 Node.js 24+。默认安装到 ~/.anatomy,并配置终端 PATH;完成后打开新终端。仓库仍需提供 anatomy.json。可用 --prefix 指定绝对路径,或用 --no-modify-path 自行管理 PATH。卸载保留终端配置及其备份,可手动移除 Anatomy PATH 条目。" } }, "quick-start": { diff --git a/bun.lock b/bun.lock index 36a551d..2c9c3a2 100644 --- a/bun.lock +++ b/bun.lock @@ -23,11 +23,13 @@ "anatomy-cli": "./bin/anatomy-cli.js", "anatomy": "./bin/anatomy.js", }, + "dependencies": { + "@anatomy-cli/anatomy": "^0.1.0", + "@anatomy-cli/schemas": "^0.1.0", + "neverthrow": "^8.2.0", + }, "devDependencies": { - "@anatomy-cli/anatomy": "workspace:*", - "@anatomy-cli/schemas": "workspace:*", "@types/node": "^25.9.2", - "neverthrow": "^8.2.0", "oxlint": "^1.59.0", "typescript": "5.9.2", "vitest": "^4.1.8", @@ -83,8 +85,9 @@ "name": "@anatomy-cli/anatomy", "version": "0.1.0", "dependencies": { - "@anatomy-cli/schemas": "workspace:*", + "@anatomy-cli/schemas": "^0.1.0", "neverthrow": "^8.2.0", + "typescript": "5.9.2", }, "devDependencies": { "@types/node": "^25.9.2", diff --git a/package.json b/package.json index c6e0423..ff0155d 100644 --- a/package.json +++ b/package.json @@ -26,8 +26,8 @@ "packages/*" ], "scripts": { - "anatomy": "bun run apps/anatomy-cli/src/main.ts", - "anatomy-cli": "bun run apps/anatomy-cli/src/main.ts", + "anatomy": "bun apps/anatomy-cli/src/main.ts", + "anatomy-cli": "bun apps/anatomy-cli/src/main.ts", "docs:dev": "bun --cwd apps/docs dev", "docs:build": "bun --cwd apps/docs build", "docs:build:cloudflare": "bun --cwd apps/docs build:cloudflare", @@ -36,7 +36,7 @@ "docs:preview": "bun --cwd apps/docs serve", "docs:check-types": "bun --cwd apps/docs check-types", "docs:lint": "bun --cwd apps/docs lint", - "build": "bun run --filter 'anatomy-cli' build", + "build": "bun run --cwd packages/schemas build && bun run --cwd packages/anatomy build && bun run --cwd apps/anatomy-cli build", "check-types": "bunx --no-install tsc --noEmit && bun run --filter '*' check-types", "lint": "bun run --filter '*' lint", "test": "bun run --filter '*' test", @@ -44,7 +44,8 @@ "anatomy:check": "bun run anatomy . --git-files" }, "engines": { - "bun": ">=1.3.0" + "bun": ">=1.3.0", + "node": ">=24" }, "packageManager": "bun@1.3.11", "devDependencies": { diff --git a/packages/anatomy-cli-config/package.json b/packages/anatomy-cli-config/package.json index cabe5c6..d0690fd 100644 --- a/packages/anatomy-cli-config/package.json +++ b/packages/anatomy-cli-config/package.json @@ -26,5 +26,8 @@ "oxlint": "^1.59.0", "typescript": "5.9.2", "vitest": "^4.1.8" + }, + "engines": { + "node": ">=24" } } diff --git a/packages/anatomy-cli-config/src/anatomies.spec.ts b/packages/anatomy-cli-config/src/anatomies.spec.ts index 094c7e5..43c0538 100644 --- a/packages/anatomy-cli-config/src/anatomies.spec.ts +++ b/packages/anatomy-cli-config/src/anatomies.spec.ts @@ -26,7 +26,7 @@ type AnatomyDefinition = { structure: { defaultPolicies: Record; root: { children: AnatomyNode[] }; - schemaVersion: number; + rootMode: "contents"; }; }; @@ -61,7 +61,7 @@ describe("anatomy CLI configuration package", () => { ) as AnatomyDefinition; const ids = collectIds(definition.structure.root.children); - expect(definition.structure.schemaVersion, filename).toBe(1); + expect(definition.structure.rootMode, filename).toBe("contents"); expect(definition.structure.defaultPolicies, filename).toEqual({ missingRequired: "block", nameMismatch: "block", diff --git a/packages/anatomy-cli-config/src/anatomies/dao.anatomy.json b/packages/anatomy-cli-config/src/anatomies/dao.anatomy.json index 7c7eaaa..226fc0c 100644 --- a/packages/anatomy-cli-config/src/anatomies/dao.anatomy.json +++ b/packages/anatomy-cli-config/src/anatomies/dao.anatomy.json @@ -2,7 +2,7 @@ "name": "DAO operation units", "purpose": "Require every DAO to aggregate independently tested, folderized persistence operations with colocated barrel exports.", "structure": { - "schemaVersion": 1, + "rootMode": "contents", "defaultPolicies": { "missingRequired": "block", "unexpectedEntry": "block", diff --git a/packages/anatomy-cli-config/src/anatomies/drizzle-relation.anatomy.json b/packages/anatomy-cli-config/src/anatomies/drizzle-relation.anatomy.json index c5013da..6d94b48 100644 --- a/packages/anatomy-cli-config/src/anatomies/drizzle-relation.anatomy.json +++ b/packages/anatomy-cli-config/src/anatomies/drizzle-relation.anatomy.json @@ -2,7 +2,7 @@ "name": "Tellyn Drizzle relation files", "purpose": "Require domain-grouped Drizzle relation modules to use the singular *.relation.ts suffix and explicit barrels.", "structure": { - "schemaVersion": 1, + "rootMode": "contents", "defaultPolicies": { "missingRequired": "block", "unexpectedEntry": "block", diff --git a/packages/anatomy-cli-config/src/anatomies/drizzle-table.anatomy.json b/packages/anatomy-cli-config/src/anatomies/drizzle-table.anatomy.json index 2f0e147..25f80f3 100644 --- a/packages/anatomy-cli-config/src/anatomies/drizzle-table.anatomy.json +++ b/packages/anatomy-cli-config/src/anatomies/drizzle-table.anatomy.json @@ -2,7 +2,7 @@ "name": "Tellyn Drizzle table files", "purpose": "Require domain-grouped Drizzle table modules to use the *.table.ts suffix and explicit barrels.", "structure": { - "schemaVersion": 1, + "rootMode": "contents", "defaultPolicies": { "missingRequired": "block", "unexpectedEntry": "block", diff --git a/packages/anatomy-cli-config/src/anatomies/mobile-screen.anatomy.json b/packages/anatomy-cli-config/src/anatomies/mobile-screen.anatomy.json index c754827..e942fe4 100644 --- a/packages/anatomy-cli-config/src/anatomies/mobile-screen.anatomy.json +++ b/packages/anatomy-cli-config/src/anatomies/mobile-screen.anatomy.json @@ -2,7 +2,7 @@ "name": "Tellyn mobile screen files", "purpose": "Require every mobile screen to use a dedicated *Screen directory with a main component, Storybook story, and barrel.", "structure": { - "schemaVersion": 1, + "rootMode": "contents", "defaultPolicies": { "missingRequired": "block", "unexpectedEntry": "block", diff --git a/packages/anatomy-cli-config/src/anatomies/repository.anatomy.json b/packages/anatomy-cli-config/src/anatomies/repository.anatomy.json index e4777c1..ba318a8 100644 --- a/packages/anatomy-cli-config/src/anatomies/repository.anatomy.json +++ b/packages/anatomy-cli-config/src/anatomies/repository.anatomy.json @@ -2,7 +2,7 @@ "name": "Repository operation units", "purpose": "Require every Repository to aggregate independently tested, folderized transaction operations with colocated barrel exports.", "structure": { - "schemaVersion": 1, + "rootMode": "contents", "defaultPolicies": { "missingRequired": "block", "unexpectedEntry": "block", diff --git a/packages/anatomy-cli-config/src/anatomies/schemas.anatomy.json b/packages/anatomy-cli-config/src/anatomies/schemas.anatomy.json index b697923..ae63eec 100644 --- a/packages/anatomy-cli-config/src/anatomies/schemas.anatomy.json +++ b/packages/anatomy-cli-config/src/anatomies/schemas.anatomy.json @@ -2,7 +2,7 @@ "name": "Schemas package structure", "purpose": "Require every Zod schema module to live inside a domain directory, use the *.schema.ts suffix, and expose that domain through an index.ts barrel.", "structure": { - "schemaVersion": 1, + "rootMode": "contents", "defaultPolicies": { "missingRequired": "block", "unexpectedEntry": "block", diff --git a/packages/anatomy-cli-config/src/anatomies/service.anatomy.json b/packages/anatomy-cli-config/src/anatomies/service.anatomy.json index 8298926..6676489 100644 --- a/packages/anatomy-cli-config/src/anatomies/service.anatomy.json +++ b/packages/anatomy-cli-config/src/anatomies/service.anatomy.json @@ -2,7 +2,7 @@ "name": "Tellyn Service files", "purpose": "Require PascalCase *Service modules with explicit barrels and conventional helper, method, and schema submodules.", "structure": { - "schemaVersion": 1, + "rootMode": "contents", "defaultPolicies": { "missingRequired": "block", "unexpectedEntry": "block", diff --git a/packages/anatomy-cli-config/src/anatomies/trpc-router.anatomy.json b/packages/anatomy-cli-config/src/anatomies/trpc-router.anatomy.json index 1a75134..3c83932 100644 --- a/packages/anatomy-cli-config/src/anatomies/trpc-router.anatomy.json +++ b/packages/anatomy-cli-config/src/anatomies/trpc-router.anatomy.json @@ -2,7 +2,7 @@ "name": "tRPC Router catalogue", "purpose": "Require every tRPC Router to aggregate named-exported query and mutation Procedures, with each Procedure and its unit test colocated in an isolated directory and input validation defined inline.", "structure": { - "schemaVersion": 1, + "rootMode": "contents", "defaultPolicies": { "missingRequired": "block", "unexpectedEntry": "block", diff --git a/packages/anatomy-cli-config/src/anatomies/zod-schema.anatomy.json b/packages/anatomy-cli-config/src/anatomies/zod-schema.anatomy.json index 266558d..2089acc 100644 --- a/packages/anatomy-cli-config/src/anatomies/zod-schema.anatomy.json +++ b/packages/anatomy-cli-config/src/anatomies/zod-schema.anatomy.json @@ -2,7 +2,7 @@ "name": "Tellyn Zod schema files", "purpose": "Require shared Zod schema modules to use the *.schema.ts suffix; tests live outside the schemas package.", "structure": { - "schemaVersion": 1, + "rootMode": "contents", "defaultPolicies": { "missingRequired": "block", "unexpectedEntry": "block", diff --git a/packages/anatomy/package.json b/packages/anatomy/package.json index 0767b85..3e909c4 100644 --- a/packages/anatomy/package.json +++ b/packages/anatomy/package.json @@ -5,23 +5,50 @@ "license": "MIT", "type": "module", "exports": { - ".": "./src/index.ts", - "./core": "./src/core/index.ts" + ".": { + "types": "./dist/index.d.ts", + "default": "./dist/index.js" + }, + "./core": { + "types": "./dist/core/index.d.ts", + "default": "./dist/core/index.js" + }, + "./source": { + "types": "./dist/source/index.d.ts", + "default": "./dist/source/index.js" + }, + "./composition": { + "types": "./dist/composition/index.d.ts", + "default": "./dist/composition/index.js" + } }, "scripts": { "check-types": "tsc --noEmit", "lint": "oxlint src/", "test": "vitest run", - "quality": "bun run check-types && bun run lint && bun run test" + "quality": "bun run check-types && bun run lint && bun run test", + "build": "rm -rf dist && tsc -p tsconfig.build.json", + "prepack": "bun run build" }, "dependencies": { - "@anatomy-cli/schemas": "workspace:*", - "neverthrow": "^8.2.0" + "@anatomy-cli/schemas": "^0.1.0", + "neverthrow": "^8.2.0", + "typescript": "5.9.2" }, "devDependencies": { "@types/node": "^25.9.2", "oxlint": "^1.59.0", "typescript": "5.9.2", "vitest": "^4.1.8" + }, + "files": [ + "dist" + ], + "types": "./dist/index.d.ts", + "publishConfig": { + "access": "public" + }, + "engines": { + "node": ">=24" } } diff --git a/packages/anatomy/src/composition/AnatomyResourceLimits.ts b/packages/anatomy/src/composition/AnatomyResourceLimits.ts new file mode 100644 index 0000000..27bf79c --- /dev/null +++ b/packages/anatomy/src/composition/AnatomyResourceLimits.ts @@ -0,0 +1,9 @@ +export const AnatomyResourceLimits = { + definitions: 128, + objects: 100_000, + inputDepth: 128, + referenceDepth: 32, + mounts: 10_000, + sourceBytes: 5_000_000, + totalSourceBytes: 20_000_000, +} as const; diff --git a/packages/anatomy/src/composition/checkInputBudget.ts b/packages/anatomy/src/composition/checkInputBudget.ts new file mode 100644 index 0000000..2c2d76f --- /dev/null +++ b/packages/anatomy/src/composition/checkInputBudget.ts @@ -0,0 +1,43 @@ +import { err, ok } from "neverthrow"; +import type { AnatomyDiagnostic } from "@anatomy-cli/schemas"; +import { AnatomyResourceLimits } from "./AnatomyResourceLimits.js"; + +export const checkInputBudget = (input: unknown) => { + const active = new Set(); + const stack = [{ value: input, depth: 0, leave: false }]; + let count = 0; + while (stack.length) { + const { value, depth, leave } = stack.pop()!; + if (value === null || typeof value !== "object") continue; + if (leave) { + active.delete(value); + continue; + } + if ( + ++count > AnatomyResourceLimits.objects || + depth > AnatomyResourceLimits.inputDepth || + active.has(value) + ) { + return err({ + code: "resource_limit_exceeded", + message: + "Input exceeds the object/depth budget or contains an object cycle", + }); + } + active.add(value); + stack.push({ value, depth, leave: true }); + const values = Object.values(value); + if ( + values.length > AnatomyResourceLimits.objects || + stack.length + values.length > AnatomyResourceLimits.objects * 2 + ) { + return err({ + code: "resource_limit_exceeded", + message: "Input container exceeds the traversal budget", + }); + } + for (const child of values) + stack.push({ value: child, depth: depth + 1, leave: false }); + } + return ok(undefined); +}; diff --git a/packages/anatomy/src/composition/compileAnatomyDefinition.ts b/packages/anatomy/src/composition/compileAnatomyDefinition.ts new file mode 100644 index 0000000..60262f7 --- /dev/null +++ b/packages/anatomy/src/composition/compileAnatomyDefinition.ts @@ -0,0 +1,105 @@ +import type { + AnatomyDefinition, + AnatomyRule, + AnatomyNode, + AnatomyDraftInput, + AnatomyOrigin, + AnatomyCompositionNode, +} from "@anatomy-cli/schemas"; + +export const compileAnatomyDefinition = ( + key: string, + definition: AnatomyDefinition, + definitions: ReadonlyMap, + originalDefinition: unknown = definition, +) => { + const origins = new Map(); + const nodes = new Map(); + const mounts = new Map(); + let counter = 0; + const convert = (node: AnatomyRule, path: string): AnatomyNode => { + const id = `00000000-0000-4000-8000-${String(++counter).padStart(12, "0")}`; + let original: unknown = originalDefinition; + for (const part of path.split("/").slice(1)) + original = + original && typeof original === "object" + ? (original as Record)[part] + : undefined; + const sourceId = + original && typeof original === "object" + ? (original as { id?: unknown }).id + : undefined; + origins.set(id, { + definitionKey: key, + rulePath: path, + sourceNodeId: typeof sourceId === "string" ? sourceId : null, + }); + nodes.set(id, node); + if (node.kind === "composition") { + mounts.set(id, node); + const root = definitions.get(node.ref)?.structure; + const name = + root?.rootMode === "entry" + ? root.root.name + : (node.name ?? { type: "literal", value: "unavailable" }); + return { + kind: "directory", + id, + name, + quantity: node.quantity, + policyOverrides: node.policyOverrides, + children: [], + }; + } + if (node.kind === "directory") + return { + ...node, + id, + children: node.children.map((child, i) => + convert(child, `${path}/children/${i}`), + ), + }; + if (node.kind === "one_of") + return { + ...node, + id, + alternatives: node.alternatives.map( + (child, i) => + convert(child, `${path}/alternatives/${i}`) as Exclude< + AnatomyNode, + { kind: "one_of" } + >, + ), + }; + return { ...node, id }; + }; + const structure = definition.structure; + const entryRoot = structure.rootMode === "entry"; + const children = entryRoot + ? [convert(structure.root, "/structure/root")] + : structure.root.children.map((node, i) => + convert(node, `/structure/root/children/${i}`), + ); + const compiledDefinition: AnatomyDraftInput = { + name: definition.name, + purpose: definition.purpose, + structure: { + rootMode: "contents", + defaultPolicies: structure.defaultPolicies, + bindings: structure.bindings, + root: { children }, + }, + }; + return { + key, + definition, + compiledDefinition, + origins, + nodes, + mounts, + entryRoot, + }; +}; +export type CompiledAnatomyDefinition = ReturnType< + typeof compileAnatomyDefinition +>; diff --git a/packages/anatomy/src/composition/composition.spec.ts b/packages/anatomy/src/composition/composition.spec.ts new file mode 100644 index 0000000..723612c --- /dev/null +++ b/packages/anatomy/src/composition/composition.spec.ts @@ -0,0 +1,667 @@ +import { readFileSync } from "node:fs"; +import { resolve } from "node:path"; +import { describe, expect, it } from "vitest"; +import { scanAnatomy } from "./scanAnatomy.js"; +import { queryAnatomyBundle } from "./queryAnatomyBundle.js"; +import { validateAnatomyBundle } from "./validateAnatomyBundle.js"; +import { + AnatomyScanOutcomeSchema, + AnatomyBundleQueryOutcomeSchema, +} from "@anatomy-cli/schemas"; + +const load = () => + JSON.parse( + readFileSync( + resolve( + import.meta.dirname, + "../../../../apps/anatomy-cli/anatomies/db-schema.bundle.json", + ), + "utf8", + ), + ); +const file = (name: string) => ({ kind: "file" as const, name }); +const dir = (name: string, children: any[] = []) => ({ + kind: "directory" as const, + name, + children, +}); +const domain = (name: string) => + dir(name, [file("index.ts"), file(`${name}.table.ts`)]); +const target = () => + dir("db-schema", [ + file("package.json"), + file("tsconfig.json"), + dir("src", [ + file("index.ts"), + dir("tables", [file("index.ts"), domain("accounts"), domain("billing")]), + dir("relations", [file("index.ts")]), + ]), + ]); +const definition = (b: any, key: string) => + b.definitions.find((d: any) => d.key === key).definition; +const check = ( + bundle: any, + tree = target(), + sources?: Record, +) => + scanAnatomy({ + bundle, + target: tree, + coverage: { status: "complete" }, + sources, + }); +const at = (tree: any, path: string): any => + path + .split("/") + .reduce((n, p) => n.children.find((c: any) => c.name === p), tree); +const codes = (r: Awaited>) => + r.status === "error" + ? r.diagnostics.map((d) => d.code) + : r.issues.map((d) => d.code); + +describe("portable directory compositions", () => { + /** @summary Show the Domain directory in an independent view + * @description Given: Table Domain has an explicit domain root. + * When: The maintainer queries its root. + * Then: The result includes that directory and its own children. + */ + it("[AC-01] independently describes the Domain root", () => { + const b = load(); + b.root = "table-domain"; + const r = queryAnatomyBundle({ bundle: b, path: "." }); + expect(AnatomyBundleQueryOutcomeSchema.safeParse(r).success).toBe(true); + expect(r).toMatchObject({ + status: "resolved", + rules: [ + { + origin: { + definitionKey: "table-domain", + rulePath: "/structure/root", + }, + node: { kind: "directory", name: { value: "" } }, + }, + ], + }); + if (r.status !== "error") + expect(r.rules[0]?.node).toHaveProperty( + "children", + expect.arrayContaining([ + expect.objectContaining({ + name: { type: "literal", value: "index.ts" }, + }), + ]), + ); + }); + /** @summary Scan repeated Domain roots without a second wrapper + * @description Given: Two valid table domains share one definition. + * When: The maintainer scans the package. + * Then: Both pass without accounts/accounts nesting. + */ + it("[AC-02][AC-03][AC-05][AC-19] scans the five-definition package", async () => { + const r = await check(load()); + expect(r).toMatchObject({ + status: "completed", + conforms: true, + issues: [], + }); + expect(AnatomyScanOutcomeSchema.safeParse(r).success).toBe(true); + }); + it("[AC-04] blocks no table domains", async () => { + const t = target(); + at(t, "src/tables").children = [file("index.ts")]; + expect(codes(await check(load(), t))).toContain("missing_required"); + }); + it("[AC-06] blocks an existing empty relation domain", async () => { + const t = target(); + at(t, "src/relations").children.push(dir("accounts", [file("index.ts")])); + const r = await check(load(), t); + expect(r).toMatchObject({ status: "completed", conforms: false }); + if (r.status === "completed") + expect(r.issues[0]).toMatchObject({ + origin: { definitionKey: "relation-domain" }, + entryPath: "src/relations/accounts", + }); + }); + it.each([ + "package.json", + "src/index.ts", + "src/tables/index.ts", + "src/tables/accounts/index.ts", + ])("[AC-07] attributes missing %s", async (path) => { + const t = target(); + const parts = path.split("/"); + const name = parts.pop(); + const parent = parts.length ? at(t, parts.join("/")) : t; + parent.children = parent.children.filter((e: any) => e.name !== name); + const r = await check(load(), t); + expect(codes(r)).toContain("missing_required"); + if (r.status === "completed") + expect(r.issues[0]!.origin.sourceNodeId).toBeNull(); + }); + it.each([ + dir("users"), + file("users.table.type-test.ts"), + file("users.type-test.table.ts"), + ])("[AC-08][AC-09] rejects extra entry $name", async (extra) => { + const t = target(); + at(t, "src/tables/accounts").children.push(extra); + const before = JSON.stringify(t); + expect(codes(await check(load(), t))).toContain("unexpected_entry"); + expect(JSON.stringify(t)).toBe(before); + }); + it("[AC-10] does not require relations for every table or equal domains", async () => { + const t = target(); + at(t, "src/relations").children.push( + dir("cross", [file("index.ts"), file("external.relation.ts")]), + ); + expect( + await check(load(), t, { + "src/relations/cross/external.relation.ts": + "import { accounts } from '../../tables/accounts/accounts.table.js';", + }), + ).toMatchObject({ conforms: true }); + }); + it("[AC-11] accepts a diamond dependency", () => { + const b = load(); + const relations = definition(b, "relations-class"); + relations.structure.root.children[1].ref = "table-domain"; + expect(validateAnatomyBundle(b).status).toBe("valid"); + }); + it.each(["db-schema-package", "tables-class"])( + "[AC-12] rejects cycle to %s", + async (ref) => { + const b = load(); + const n = definition(b, "tables-class").structure.root.children[1]; + n.ref = ref; + n.name = { type: "placeholder", value: "" }; + const r = await check(b); + expect(codes(r)).toContain("composition_cycle"); + if (r.status === "error") + expect( + r.diagnostics.find((d) => d.code === "composition_cycle")?.chain + ?.length, + ).toBeGreaterThan(1); + }, + ); + it("[AC-13] validates absent optional references", async () => { + const b = load(); + definition(b, "relations-class").structure.root.children[1].ref = + "unavailable"; + const r = await check(b); + expect(codes(r)).toContain("unavailable_reference"); + expect(r).toHaveProperty("conforms", null); + }); + it.each(["composition", "directory"])( + "[AC-14] rejects overlapping %s ownership", + async (kind) => { + const b = load(); + const nodes = definition(b, "tables-class").structure.root.children; + nodes.push( + kind === "composition" + ? { + kind, + ref: "table-domain", + quantity: "zero_or_more", + policyOverrides: {}, + } + : { + kind, + name: { type: "literal", value: "accounts" }, + quantity: "exactly_one", + policyOverrides: {}, + children: [], + }, + ); + expect(codes(await check(b))).toContain("ambiguous_mount"); + }, + ); + it("[AC-15] keeps distinct deterministic identities and original pointers", async () => { + const b = load(); + const t = target(); + for (const name of ["accounts", "billing"]) + at(t, `src/tables/${name}`).children.shift(); + const a = await check(b, t); + const c = await check(b, t); + expect(a).toEqual(c); + if (a.status === "completed") { + expect(a.issues).toHaveLength(2); + expect(new Set(a.issues.map((i) => i.issueKey)).size).toBe(2); + expect(a.issues.map((i) => i.origin.rulePath)).toEqual([ + "/structure/root/children/0", + "/structure/root/children/0", + ]); + expect(a.issues.map((i) => i.mounts.at(-1)?.mountPath).sort()).toEqual([ + "src/tables/accounts", + "src/tables/billing", + ]); + } + }); + it("[AC-16] preserves child blocking policies", async () => { + const b = load(); + definition(b, "tables-class").structure.root.children[1].policyOverrides = { + missingRequired: "warn", + }; + const t = target(); + at(t, "src/tables/accounts").children.shift(); + const r = await check(b, t); + if (r.status !== "completed") throw new Error(JSON.stringify(r)); + expect(r.issues[0]).toMatchObject({ + severity: "block", + policyOrigin: { + origin: { + definitionKey: "table-domain", + rulePath: "/structure/defaultPolicies", + }, + }, + }); + }); + it("[AC-17] mounts named contents definitions", async () => { + const b = load(); + const d = definition(b, "table-domain"); + d.structure = { + rootMode: "contents", + defaultPolicies: d.structure.defaultPolicies, + root: { children: d.structure.root.children }, + }; + definition(b, "tables-class").structure.root.children[1].name = { + type: "placeholder", + value: "", + }; + expect(await check(b)).toMatchObject({ conforms: true }); + }); + it("[AC-18] validates an independent target root name", async () => { + const b = load(); + b.root = "table-domain"; + definition(b, b.root).structure.root.name = { + type: "literal", + value: "accounts", + }; + expect(codes(await check(b, domain("billing")))).toEqual(["name_mismatch"]); + }); + it("[AC-20] returns completed for structural nonconformance", async () => { + expect(await check(load(), dir("db-schema", []))).toMatchObject({ + status: "completed", + conforms: false, + }); + }); + it("[AC-21] rejects incomplete trees", async () => { + expect( + await scanAnatomy({ + bundle: load(), + target: target(), + coverage: { + status: "incomplete", + reason: "provider truncated", + paths: ["src"], + }, + }), + ).toMatchObject({ + status: "error", + conforms: null, + diagnostics: [{ code: "incomplete_tree" }], + }); + }); + it("[AC-22] requires source for selected export rules", async () => { + const b = load(); + b.root = "table-domain"; + definition(b, b.root).structure.root.children[1].exports = { + name: "file_stem", + policy: "block", + }; + expect(codes(await check(b, domain("accounts")))).toEqual([ + "source_unavailable", + ]); + expect( + codes( + await check(b, domain("accounts"), { + "accounts.table.ts": "export const wrong = 1", + }), + ), + ).toContain("export_kind_mismatch"); + }); + it.each(["duplicate", "missing-root", "root-mode", "invalid-name"])( + "[AC-23] rejects invalid bundle %s", + async (kind) => { + const b = load(); + if (kind === "duplicate") b.definitions.push(b.definitions[0]); + if (kind === "missing-root") b.root = "absent"; + if (kind === "root-mode") + definition(b, b.root).structure.rootMode = "unknown"; + if (kind === "invalid-name") + definition(b, "table-domain").structure.root.name.value = "../bad"; + expect(await check(b)).toMatchObject({ status: "error", conforms: null }); + }, + ); + it.each([dir(".."), file("a/b"), file("index.ts")])( + "[AC-23] rejects invalid tree $name", + async (e) => { + const t = target(); + at(t, "src").children.push(e); + expect(codes(await check(load(), t))).toContain("invalid_tree"); + }, + ); + it("[AC-24] returns both mount and referenced root", () => { + const r = queryAnatomyBundle({ + bundle: load(), + path: "src/tables/accounts", + }); + expect(r.status).toBe("resolved"); + if (r.status !== "error") + expect( + r.rules.map((r) => [r.origin.definitionKey, r.origin.rulePath]), + ).toEqual([ + ["tables-class", "/structure/root/children/1"], + ["table-domain", "/structure/root"], + ]); + }); + it("queries descendants using fresh child captures", () => { + const r = queryAnatomyBundle({ + bundle: load(), + path: "src/tables/accounts/accounts.table.ts", + }); + expect(r.status).toBe("resolved"); + expect(AnatomyBundleQueryOutcomeSchema.safeParse(r).success).toBe(true); + if (r.status !== "error") + expect(r.rules[0]?.origin.definitionKey).toBe("table-domain"); + }); + it("[AC-27] rejects object cycles without overflowing", async () => { + const t: any = target(); + t.children.push(t); + expect(codes(await check(load(), t))).toEqual(["resource_limit_exceeded"]); + }); + it("ignores absent references in unreachable definitions without crashing", async () => { + const b = load(); + b.definitions.push({ + key: "unused", + definition: { + ...definition(b, "relations-class"), + structure: { + ...definition(b, "relations-class").structure, + root: { + children: [ + { + kind: "composition", + ref: "absent", + name: { type: "literal", value: "mount" }, + quantity: "optional", + }, + ], + }, + }, + }, + }); + expect(await check(b)).toMatchObject({ conforms: true }); + }); +}); + +describe("composition boundary regressions", () => { + it("keeps an index file out of a domain mount even if the mount is declared first", async () => { + const b = load(); + definition(b, "tables-class").structure.root.children.reverse(); + expect(await check(b)).toMatchObject({ conforms: true }); + }); + it("attributes a wrong-kind mount to its parent", async () => { + const t = target(); + at(t, "src").children = at(t, "src").children.map((e: any) => + e.name === "tables" ? file("tables") : e, + ); + const r = await check(load(), t); + expect(r).toMatchObject({ + status: "completed", + issues: expect.arrayContaining([ + expect.objectContaining({ + code: "nesting_mismatch", + origin: expect.objectContaining({ + definitionKey: "db-schema-package", + }), + }), + ]), + }); + }); + it("does not suppress ordinary duplicate names just because another mount exists", () => { + const b = load(); + const nodes = definition(b, "tables-class").structure.root.children; + nodes.push({ ...nodes[0] }); + expect(validateAnatomyBundle(b).status).toBe("error"); + }); + it("rejects two same-literal mounts at execution with an ambiguity diagnostic", async () => { + const b = load(); + const nodes = definition(b, "db-schema-package").structure.root.children[2] + .children; + nodes.push({ ...nodes[1] }); + expect(codes(await check(b))).toContain("ambiguous_mount"); + }); + it("preserves child bindings independently of the parent's binding with the same name", async () => { + const b = load(); + definition(b, "tables-class").structure.bindings = { + domain: { pattern: "not-a-real-domain" }, + }; + definition(b, "table-domain").structure.bindings = { + domain: { format: "camelCase" }, + }; + expect(await check(b)).toMatchObject({ conforms: true }); + expect( + queryAnatomyBundle({ + bundle: b, + path: "src/tables/accounts/accounts.table.ts", + }), + ).toMatchObject({ status: "resolved" }); + }); + it("attributes ordinary inherited overrides to the original ancestor", async () => { + const b = load(); + definition(b, "table-domain").structure.root.policyOverrides = { + unexpectedEntry: "warn", + }; + const t = target(); + at(t, "src/tables/accounts").children.push(file("extra.ts")); + const r = await check(b, t); + if (r.status !== "completed") throw new Error(JSON.stringify(r)); + expect(r.issues[0]).toMatchObject({ + severity: "warn", + policyOrigin: { + origin: { definitionKey: "table-domain", rulePath: "/structure/root" }, + policy: "unexpectedEntry", + }, + }); + }); + it("allows duplicate node IDs in different definitions", async () => { + const b = load(); + const id = "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa"; + definition(b, "table-domain").structure.root.id = id; + definition(b, "relation-domain").structure.root.id = id; + expect(await check(b)).toMatchObject({ conforms: true }); + }); + it("checks source functions through the shared lazy analyzer", async () => { + const b = load(); + b.root = "table-domain"; + const d = definition(b, b.root); + d.structure.root.children = [ + { + kind: "file", + name: { type: "literal", value: "getUser.ts" }, + quantity: "exactly_one", + exports: { name: "file_stem", policy: "block" }, + }, + ]; + expect( + await check(b, dir("accounts", [file("getUser.ts")]), { + "getUser.ts": + "export type User = {}; export function getUser() { return 1; }", + }), + ).toMatchObject({ conforms: true }); + expect( + codes( + await check(b, dir("accounts", [file("getUser.ts")]), { + "getUser.ts": "export function getUser( {", + }), + ), + ).toEqual(["source_analysis_error"]); + }); + it("rejects an entry-reference override name and inline composition children", () => { + for (const change of [ + { name: { type: "literal", value: "accounts" } }, + { children: [] }, + ]) { + const b = load(); + Object.assign( + definition(b, "tables-class").structure.root.children[1], + change, + ); + expect(validateAnatomyBundle(b).status).toBe("error"); + } + }); + it("requires a root mode and rejects composition alternatives", () => { + const b = load(); + const d = definition(b, "tables-class"); + delete d.structure.rootMode; + expect(validateAnatomyBundle(b).status).toBe("error"); + const c = load(); + definition(c, "tables-class").structure.root.children = [ + { + kind: "one_of", + minimumMatches: 1, + maximumMatches: 1, + alternatives: [ + { kind: "composition", ref: "table-domain", quantity: "exactly_one" }, + { + kind: "file", + name: { type: "literal", value: "index.ts" }, + quantity: "exactly_one", + }, + ], + }, + ]; + expect(validateAnatomyBundle(c).status).toBe("error"); + }); + it("does not emit partial findings when a later source is absent", async () => { + const b = load(); + definition(b, "table-domain").structure.root.children[1].exports = { + name: "file_stem", + policy: "block", + }; + const r = await check(b, target(), { + "src/tables/accounts/accounts.table.ts": "export const wrong=1", + }); + expect(r).toMatchObject({ status: "error", conforms: null }); + expect(r).not.toHaveProperty("issues"); + }); + it("keeps identities invariant under input permutations", async () => { + const b = load(); + const t = target(); + at(t, "src/tables/accounts").children.shift(); + const first = await check(b, t); + b.definitions.reverse(); + t.children.reverse(); + at(t, "src/tables").children.reverse(); + expect(await check(b, t)).toEqual(first); + }); +}); + +describe("SDK execution budgets", () => { + it("limits bundle definition count", () => { + const b = load(); + const template = definition(b, "relations-class"); + b.definitions = Array.from({ length: 129 }, (_, i) => ({ + key: `definition-${i}`, + definition: { + ...template, + structure: { ...template.structure, root: { children: [] } }, + }, + })); + b.root = "definition-0"; + expect(validateAnatomyBundle(b)).toMatchObject({ + status: "error", + diagnostics: [{ code: "resource_limit_exceeded" }], + }); + }); + it("limits the longest reference path even through shared definitions", () => { + const b = load(); + const template = definition(b, "relations-class"); + b.definitions = Array.from({ length: 35 }, (_, i) => ({ + key: `definition-${i}`, + definition: { + ...template, + structure: { + ...template.structure, + root: { + children: + i < 34 + ? [ + { + kind: "composition", + ref: `definition-${i + 1}`, + name: { type: "literal", value: "child" }, + quantity: "optional", + }, + ] + : [], + }, + }, + }, + })); + b.root = "definition-0"; + expect(validateAnatomyBundle(b)).toMatchObject({ + status: "error", + diagnostics: expect.arrayContaining([ + expect.objectContaining({ code: "resource_limit_exceeded" }), + ]), + }); + }); + it("limits UTF-8 bytes per source before source parsing", async () => { + expect( + codes( + await check(load(), target(), { "big.ts": "中".repeat(1_666_667) }), + ), + ).toEqual(["resource_limit_exceeded"]); + }); + it("limits total source bytes", async () => { + const sources = Object.fromEntries( + Array.from({ length: 5 }, (_, i) => [ + `file-${i}.ts`, + "x".repeat(4_000_001), + ]), + ); + expect(codes(await check(load(), target(), sources))).toEqual([ + "resource_limit_exceeded", + ]); + }); + it("keeps root and immediate child policy overrides in root queries", () => { + const b = load(); + b.root = "table-domain"; + definition(b, b.root).structure.root.policyOverrides = { + unexpectedEntry: "warn", + }; + expect(queryAnatomyBundle({ bundle: b, path: "." })).toMatchObject({ + status: "resolved", + rules: [{ policies: { unexpectedEntry: "warn" } }], + }); + b.root = "tables-class"; + definition(b, b.root).structure.root.children[0].policyOverrides = { + missingRequired: "warn", + }; + expect(queryAnatomyBundle({ bundle: b, path: "." })).toMatchObject({ + status: "resolved", + rules: expect.arrayContaining([ + expect.objectContaining({ + policies: expect.objectContaining({ missingRequired: "warn" }), + }), + ]), + }); + }); + it.each(["schemaVersion", "bundleVersion"])( + "rejects obsolete %s fields instead of selecting a compatibility branch", + async (field) => { + const b = load(); + if (field === "schemaVersion") definition(b, b.root).structure[field] = 1; + else b[field] = 1; + expect(codes(await check(b))).toEqual(["invalid_bundle"]); + }, + ); + it("returns scan and query outcomes without version selectors", async () => { + const b = load(); + const scan = await check(b); + const query = queryAnatomyBundle({ bundle: b, path: "." }); + expect(scan).not.toHaveProperty("contractVersion"); + expect(query).not.toHaveProperty("contractVersion"); + }); +}); diff --git a/packages/anatomy/src/composition/createAnatomyFinding.ts b/packages/anatomy/src/composition/createAnatomyFinding.ts new file mode 100644 index 0000000..e4c6586 --- /dev/null +++ b/packages/anatomy/src/composition/createAnatomyFinding.ts @@ -0,0 +1,79 @@ +import type { + AnatomyFinding, + AnatomyMount, + AnatomyPolicies, + AnatomyOrigin, +} from "@anatomy-cli/schemas"; +import type { + AnatomyCheckIssue, + AnatomyPlanHooks, +} from "../core/planAnatomyCheck.js"; +import type { CompiledAnatomyDefinition } from "./compileAnatomyDefinition.js"; + +export const createAnatomyFinding = ( + issue: AnatomyCheckIssue, + unit: CompiledAnatomyDefinition, + mounts: AnatomyMount[], + mapPath: (path: string) => string, + context: Parameters>[1], +): AnatomyFinding => { + const root: AnatomyOrigin = { + definitionKey: unit.key, + rulePath: "/structure/root", + sourceNodeId: null, + }; + const ownerId = issue.constraintId ?? context.ancestors.at(-1)?.id; + const origin = ownerId ? (unit.origins.get(ownerId) ?? root) : root; + const rule = issue.constraintId + ? unit.nodes.get(issue.constraintId) + : undefined; + const sourceExport = issue.code.startsWith("export_"); + let policyOrigin: AnatomyOrigin = { + ...root, + rulePath: "/structure/defaultPolicies", + }; + for (const ancestor of context.ancestors) { + if (ancestor.overrides[context.policyKey] !== undefined) + policyOrigin = unit.origins.get(ancestor.id)!; + } + if ( + rule && + rule.kind !== "one_of" && + rule.policyOverrides[context.policyKey] !== undefined + ) + policyOrigin = origin; + if (sourceExport) policyOrigin = origin; + const entryPath = mapPath(issue.path); + const instanceKey = JSON.stringify([ + unit.key, + mounts.map((m) => [ + m.owner.definitionKey, + m.owner.rulePath, + m.ref, + m.mountPath, + ]), + ]); + return { + code: issue.code, + severity: issue.severity, + message: issue.message, + entryPath, + scopePath: mapPath(context.parentPath), + origin, + mounts, + captures: { ...context.scope }, + policyOrigin: { + origin: policyOrigin, + policy: sourceExport + ? "exports" + : (context.policyKey as keyof AnatomyPolicies), + }, + instanceKey, + issueKey: JSON.stringify([ + instanceKey, + origin.rulePath, + entryPath, + issue.code, + ]), + }; +}; diff --git a/packages/anatomy/src/composition/index.ts b/packages/anatomy/src/composition/index.ts new file mode 100644 index 0000000..5ee28f2 --- /dev/null +++ b/packages/anatomy/src/composition/index.ts @@ -0,0 +1,5 @@ +export * from "./scanAnatomy.js"; +export * from "./validateAnatomyBundle.js"; +export * from "./queryAnatomyBundle.js"; +export * from "./AnatomyResourceLimits.js"; +export * from "./planAnatomyBundle.js"; diff --git a/packages/anatomy/src/composition/planAnatomyBundle.ts b/packages/anatomy/src/composition/planAnatomyBundle.ts new file mode 100644 index 0000000..4566301 --- /dev/null +++ b/packages/anatomy/src/composition/planAnatomyBundle.ts @@ -0,0 +1,295 @@ +import { + AnatomyScanRequestSchema, + type AnatomyDiagnostic, + type AnatomyFinding, + type AnatomyMount, + type AnatomyTarget, + type AnatomyFunctionExportCheck, + type AnatomyEntry, +} from "@anatomy-cli/schemas"; +import { err, ok } from "neverthrow"; +import { resolveAnatomyBundle } from "./resolveAnatomyBundle.js"; +import { checkInputBudget } from "./checkInputBudget.js"; +import { AnatomyResourceLimits } from "./AnatomyResourceLimits.js"; +import { createAnatomyFinding } from "./createAnatomyFinding.js"; +import { + planAnatomyCheck, + type AnatomyPlanHooks, + type AnatomyCheckIssue, +} from "../core/planAnatomyCheck.js"; +import { evaluateName } from "../core/evaluateName.js"; + +type ExportPlan = { + check: AnatomyFunctionExportCheck; + finding: (issue: AnatomyCheckIssue) => AnatomyFinding; +}; +export const planAnatomyBundle = (input: unknown) => { + const budget = checkInputBudget(input); + if (budget.isErr()) return err([budget.error]); + const parsed = AnatomyScanRequestSchema.safeParse(input); + if (!parsed.success) + return err([ + { code: "invalid_tree", message: parsed.error.message }, + ]); + const request = parsed.data; + if (request.coverage.status !== "complete") + return err([ + { code: "incomplete_tree", message: request.coverage.reason }, + ]); + const diagnostics: AnatomyDiagnostic[] = []; + const validateTree = (target: AnatomyTarget): void => { + const names = new Set(); + for (const entry of [target, ...target.children]) { + if ( + !entry.name || + /[\\/\0]/.test(entry.name) || + [".", ".."].includes(entry.name) || + /^[A-Za-z]:/.test(entry.name) + ) + diagnostics.push({ + code: "invalid_tree", + message: "Names must be single path segments", + }); + } + for (const entry of target.children) { + if (names.has(entry.name)) + diagnostics.push({ + code: "invalid_tree", + message: `Duplicate sibling ${entry.name}`, + }); + names.add(entry.name); + if (entry.kind === "directory") validateTree(entry); + } + target.children.sort((a, b) => + a.name < b.name ? -1 : a.name > b.name ? 1 : 0, + ); + }; + validateTree(request.target); + let totalBytes = 0; + for (const [path, source] of Object.entries(request.sources ?? {})) { + if ( + path.startsWith("/") || + /[\\\0]/.test(path) || + /^[A-Za-z]:/.test(path) || + path.split("/").some((p) => !p || p === ".." || p === ".") + ) + diagnostics.push({ + code: "invalid_tree", + message: "Source paths must be relative POSIX paths", + }); + const bytes = new TextEncoder().encode(source).length; + totalBytes += bytes; + if (bytes > AnatomyResourceLimits.sourceBytes) + diagnostics.push({ + code: "resource_limit_exceeded", + message: "Source file exceeds byte limit", + entryPath: path, + }); + } + if (totalBytes > AnatomyResourceLimits.totalSourceBytes) + diagnostics.push({ + code: "resource_limit_exceeded", + message: "Source collection exceeds byte limit", + }); + if (diagnostics.length) return err(diagnostics); + const resolved = resolveAnatomyBundle(request.bundle); + if (resolved.isErr()) return err(resolved.error); + const issues: AnatomyFinding[] = []; + const exports: ExportPlan[] = []; + let instances = 0; + const walk = ( + key: string, + target: AnatomyTarget, + base: string, + mounts: AnatomyMount[], + ): void => { + if (diagnostics.length) return; + if (++instances > AnatomyResourceLimits.mounts) { + diagnostics.push({ + code: "resource_limit_exceeded", + message: "Mount instance limit exceeded", + }); + return; + } + const unit = resolved.value.compiled.get(key)!; + const mapPath = (path: string) => { + const relative = unit.entryRoot + ? path === target.name || path === "." + ? "." + : path.slice(target.name.length + 1) + : path; + return relative === "." + ? base + : base === "." + ? relative + : `${base}/${relative}`; + }; + const contexts = new Map< + string, + Parameters>[1] + >(); + const matchName: NonNullable = ( + entry, + name, + scope, + ignoreCase, + ) => { + const mount = unit.mounts.get(entry.id); + if (mount) { + const child = resolved.value.compiled.get(mount.ref)!; + if (child.entryRoot) + return evaluateName( + entry, + name, + {}, + child.compiledDefinition.structure.bindings ?? {}, + ignoreCase, + ); + } + return evaluateName( + entry, + name, + scope, + unit.compiledDefinition.structure.bindings ?? {}, + ignoreCase, + ); + }; + const hooks: AnatomyPlanHooks = { + preferKindOwner: true, + matchName, + skipValidation: true, + onLevel: (nodes, actual, path, scope) => { + const entries = nodes.flatMap((n) => + n.kind === "one_of" ? n.alternatives : [n], + ); + for (const entry of actual) { + const candidates = entries.filter( + (n) => + n.kind === entry.kind && + (matchName(n, entry.name, scope, false).kind !== "none" || + matchName(n, entry.name, scope, true).kind !== "none"), + ); + if ( + candidates.length > 1 && + candidates.some((n) => unit.mounts.has(n.id)) + ) { + diagnostics.push({ + code: "ambiguous_mount", + message: `Multiple owners for ${mapPath(path === "." ? entry.name : `${path}/${entry.name}`)}`, + entryPath: mapPath( + path === "." ? entry.name : `${path}/${entry.name}`, + ), + chain: candidates.map((n) => unit.origins.get(n.id)!), + }); + return false; + } + } + return diagnostics.length === 0; + }, + onIssue: (issue, context) => + issues.push( + createAnatomyFinding(issue, unit, mounts, mapPath, context), + ), + onMatch: (entry, path, scope) => + contexts.set(`${entry.id}:${path}`, { + parentPath: path.includes("/") + ? path.slice(0, path.lastIndexOf("/")) + : ".", + ancestors: [], + scope, + policyKey: "unexpectedEntry", + }), + onDirectory: (entry, actual, path, scope) => { + const mount = unit.mounts.get(entry.id); + if (!mount) return true; + const child = resolved.value.compiled.get(mount.ref)!; + const ownMatch = evaluateName( + entry, + actual.name, + child.entryRoot ? {} : scope, + child.entryRoot + ? (child.compiledDefinition.structure.bindings ?? {}) + : (unit.compiledDefinition.structure.bindings ?? {}), + ); + walk(mount.ref, actual, mapPath(path), [ + ...mounts, + { + owner: unit.origins.get(entry.id)!, + ref: mount.ref, + mountPath: mapPath(path), + captures: + ownMatch.kind === "match" + ? { ...scope, ...ownMatch.captures } + : { ...scope }, + }, + ]); + return false; + }, + }; + if (unit.entryRoot) { + const root = unit.compiledDefinition.structure.root + .children[0] as AnatomyEntry; + const match = evaluateName( + root, + target.name, + {}, + unit.compiledDefinition.structure.bindings ?? {}, + ); + if (match.kind !== "match") { + issues.push( + createAnatomyFinding( + { + code: match.kind === "none" ? "name_mismatch" : match.kind, + severity: + root.policyOverrides.nameMismatch ?? + unit.compiledDefinition.structure.defaultPolicies.nameMismatch, + path: target.name, + constraintId: root.id, + message: `Target root ${target.name} does not match ${root.name.value}`, + }, + unit, + mounts, + mapPath, + { + parentPath: ".", + ancestors: [], + scope: {}, + policyKey: "nameMismatch", + }, + ), + ); + return; + } + } + const plan = planAnatomyCheck( + unit.compiledDefinition, + unit.entryRoot ? [target] : target.children, + hooks, + ); + if (plan.isErr()) { + diagnostics.push({ + code: "invalid_bundle", + message: plan.error.map((i) => i.message).join("; "), + }); + return; + } + for (const check of plan.value.exportChecks) { + const context = contexts.get(`${check.constraintId}:${check.path}`)!; + exports.push({ + check: { ...check, path: mapPath(check.path) }, + finding: (issue) => + createAnatomyFinding( + { ...issue, path: check.path }, + unit, + mounts, + mapPath, + context, + ), + }); + } + }; + walk(resolved.value.bundle.root, request.target, ".", []); + if (diagnostics.length) return err(diagnostics); + return ok({ issues, exports, sources: request.sources ?? {} }); +}; +export type AnatomyBundlePlan = ReturnType; diff --git a/packages/anatomy/src/composition/queryAnatomyBundle.ts b/packages/anatomy/src/composition/queryAnatomyBundle.ts new file mode 100644 index 0000000..93f9100 --- /dev/null +++ b/packages/anatomy/src/composition/queryAnatomyBundle.ts @@ -0,0 +1,235 @@ +import { + AnatomyBundleQueryRequestSchema, + type AnatomyBundleQueryOutcome, + type AnatomyMount, + type AnatomyRule, +} from "@anatomy-cli/schemas"; +import { resolveAnatomyBundle } from "./resolveAnatomyBundle.js"; +import { queryAnatomy } from "../core/queryAnatomy.js"; +import { evaluateName } from "../core/evaluateName.js"; +import { checkInputBudget } from "./checkInputBudget.js"; + +export const queryAnatomyBundle = ( + input: unknown, +): AnatomyBundleQueryOutcome => { + const budget = checkInputBudget(input); + if (budget.isErr()) + return { + operation: "query", + status: "error", + diagnostics: [budget.error], + }; + const request = AnatomyBundleQueryRequestSchema.safeParse(input); + if (!request.success) + return { + operation: "query", + status: "error", + diagnostics: [{ code: "invalid_tree", message: request.error.message }], + }; + const normalized = request.data.path.replaceAll("\\", "/"); + if ( + !normalized || + normalized.startsWith("/") || + normalized.includes("\0") || + /^[A-Za-z]:/.test(normalized) || + normalized.split("/").includes("..") + ) + return { + operation: "query", + status: "error", + diagnostics: [ + { code: "invalid_tree", message: "Query must be a relative path" }, + ], + }; + const targetName = request.data.targetName; + if ( + targetName !== undefined && + (!targetName || + /[\\/\0]/.test(targetName) || + [".", ".."].includes(targetName) || + /^[A-Za-z]:/.test(targetName)) + ) + return { + operation: "query", + status: "error", + diagnostics: [ + { + code: "invalid_tree", + message: "targetName must be a single segment", + }, + ], + }; + const resolved = resolveAnatomyBundle(request.data.bundle); + if (resolved.isErr()) + return { + operation: "query", + status: "error", + diagnostics: resolved.error, + }; + const path = + normalized + .split("/") + .filter((p) => p && p !== ".") + .join("/") || "."; + type Success = Exclude; + const walk = ( + key: string, + remaining: string, + name: string | undefined, + base: string, + mounts: AnatomyMount[], + ): AnatomyBundleQueryOutcome => { + const unit = resolved.value.compiled.get(key)!; + const mapPath = (local: string) => { + const relative = + unit.entryRoot && name + ? local === name || local === "." + ? "." + : local.slice(name.length + 1) + : local; + return relative === "." + ? base + : base === "." + ? relative + : `${base}/${relative}`; + }; + const entryRoot = unit.compiledDefinition.structure.root.children[0]; + const rootRule: Success["rules"][number] = { + origin: { + definitionKey: key, + rulePath: "/structure/root", + sourceNodeId: unit.entryRoot + ? unit.origins.get( + unit.compiledDefinition.structure.root.children[0]!.id, + )!.sourceNodeId + : null, + }, + ...(unit.entryRoot + ? { node: unit.definition.structure.root as AnatomyRule } + : {}), + policies: { + ...unit.compiledDefinition.structure.defaultPolicies, + ...(unit.entryRoot && entryRoot?.kind === "directory" + ? entryRoot.policyOverrides + : {}), + }, + }; + if (remaining === "." && (!unit.entryRoot || !name)) + return { + operation: "query", + status: "resolved", + path, + scopePath: base, + reason: null, + captures: {}, + mounts, + rules: unit.entryRoot + ? [rootRule] + : [ + rootRule, + ...unit.compiledDefinition.structure.root.children.map((n) => ({ + origin: unit.origins.get(n.id)!, + node: unit.nodes.get(n.id)!, + policies: { + ...unit.compiledDefinition.structure.defaultPolicies, + ...(n.kind === "one_of" ? {} : n.policyOverrides), + }, + })), + ], + }; + if (unit.entryRoot && !name) + return { + operation: "query", + status: "error", + diagnostics: [ + { + code: "invalid_tree", + message: + "targetName is required to query descendants of an entry root", + }, + ], + }; + const local = unit.entryRoot + ? `${name}${remaining === "." ? "" : `/${remaining}`}` + : remaining; + const parts = local.split("/"); + for (let i = 0; i < parts.length; i++) { + const prefix = parts.slice(0, i + 1).join("/"); + const query = queryAnatomy(unit.compiledDefinition, prefix, { + skipValidation: true, + matchName: (entry, actual, scope, bindings, ignoreCase) => { + const mount = unit.mounts.get(entry.id); + const child = mount + ? resolved.value.compiled.get(mount.ref) + : undefined; + return child?.entryRoot + ? evaluateName( + entry, + actual, + {}, + child.compiledDefinition.structure.bindings ?? {}, + ignoreCase, + ) + : evaluateName(entry, actual, scope, bindings, ignoreCase); + }, + }); + if (query.isErr()) + return { + operation: "query", + status: "error", + diagnostics: [ + { code: "invalid_bundle", message: "Unable to query definition" }, + ], + }; + const q = query.value; + const result: Success = { + operation: "query", + status: q.status, + path, + scopePath: mapPath(q.scopePath), + reason: q.reason, + captures: q.captures, + mounts, + rules: q.rules.map((r) => ({ + origin: unit.origins.get(r.node.id)!, + node: unit.nodes.get(r.node.id)!, + policies: r.policies, + })), + }; + if (q.status !== "resolved") return result; + const matched = q.rules.length === 1 ? q.rules[0]?.node : undefined; + const mount = matched ? unit.mounts.get(matched.id) : undefined; + if (mount && matched) { + const mountPath = mapPath(prefix); + const frame = { + owner: unit.origins.get(matched.id)!, + ref: mount.ref, + mountPath, + captures: q.captures, + }; + const child = walk( + mount.ref, + parts.slice(i + 1).join("/") || ".", + parts[i], + mountPath, + [...mounts, frame], + ); + if (i === parts.length - 1 && child.status !== "error") + return { ...child, rules: [...result.rules, ...child.rules] }; + return child; + } + if (i === parts.length - 1) return result; + } + return { + operation: "query", + status: "resolved", + path, + scopePath: base, + reason: null, + captures: {}, + mounts, + rules: [rootRule], + }; + }; + return walk(resolved.value.bundle.root, path, targetName, ".", []); +}; diff --git a/packages/anatomy/src/composition/resolveAnatomyBundle.ts b/packages/anatomy/src/composition/resolveAnatomyBundle.ts new file mode 100644 index 0000000..f887252 --- /dev/null +++ b/packages/anatomy/src/composition/resolveAnatomyBundle.ts @@ -0,0 +1,223 @@ +import { + AnatomyBundleSchema, + type AnatomyDefinition, + type AnatomyDiagnostic, + type AnatomyRule, + type AnatomyOrigin, +} from "@anatomy-cli/schemas"; +import { err, ok, Result } from "neverthrow"; +import { checkInputBudget } from "./checkInputBudget.js"; +import { AnatomyResourceLimits } from "./AnatomyResourceLimits.js"; +import { compileAnatomyDefinition } from "./compileAnatomyDefinition.js"; +import { anatomyRulePaths } from "../core/anatomyRulePaths.js"; +import { validateAnatomyForPublish } from "../core/validateAnatomyForPublish.js"; + +export const resolveAnatomyBundle = (input: unknown) => { + const budget = checkInputBudget(input); + if (budget.isErr()) return err([budget.error]); + const parsed = Result.fromThrowable( + () => AnatomyBundleSchema.safeParse(input), + (): AnatomyDiagnostic => ({ + code: "invalid_bundle", + message: "Bundle cannot be parsed", + }), + )(); + if (parsed.isErr()) return err([parsed.error]); + if (!parsed.value.success) { + return err([ + { + code: "invalid_bundle", + message: parsed.value.error.message, + }, + ]); + } + const bundle = parsed.value.data; + const definitions = new Map(); + const diagnostics: AnatomyDiagnostic[] = []; + if (bundle.definitions.length > AnatomyResourceLimits.definitions) + return err([ + { code: "resource_limit_exceeded", message: "Too many definitions" }, + ]); + for (const item of bundle.definitions) { + if (definitions.has(item.key)) + diagnostics.push({ + code: "duplicate_definition_key", + message: `Duplicate definition key ${item.key}`, + }); + definitions.set(item.key, item.definition); + } + if (!definitions.has(bundle.root)) + diagnostics.push({ + code: "missing_root", + message: `Missing root ${bundle.root}`, + }); + const edges = new Map(); + for (const [key, definition] of definitions) { + const refs: { ref: string; origin: AnatomyOrigin }[] = []; + const ids = new Set(); + const visit = (node: AnatomyRule, path: string): void => { + const origin = { + definitionKey: key, + rulePath: path, + sourceNodeId: node.id ?? null, + }; + if (ids.has(node.id)) + diagnostics.push({ + code: "invalid_bundle", + message: "Duplicate node ID within definition", + origin, + }); + ids.add(node.id); + if ( + node.kind !== "one_of" && + node.name && + (/[\\/\0]/.test(node.name.value) || + [".", ".."].includes(node.name.value) || + /^[A-Za-z]:/.test(node.name.value)) + ) + diagnostics.push({ + code: "invalid_mount", + message: "Names must be single path segments", + origin, + }); + if (node.kind === "composition") { + refs.push({ ref: node.ref, origin }); + const child = definitions.get(node.ref); + if (child) { + const entry = child.structure.rootMode === "entry"; + if (entry ? node.name !== undefined : node.name === undefined) + diagnostics.push({ + code: "invalid_mount", + message: entry + ? "Entry references inherit the target root name" + : "Contents references require a mount name", + origin, + }); + } + } + if (node.kind === "directory") + node.children.forEach((n, i) => visit(n, `${path}/children/${i}`)); + if (node.kind === "one_of") + node.alternatives.forEach((n, i) => + visit(n, `${path}/alternatives/${i}`), + ); + }; + const structure = definition.structure; + if (structure.rootMode === "entry") + visit(structure.root, "/structure/root"); + else + structure.root.children.forEach((n, i) => + visit(n, `/structure/root/children/${i}`), + ); + edges.set(key, refs); + } + const active = new Set(); + const heights = new Map(); + const visitGraph = (key: string, chain: AnatomyOrigin[]): number => { + if (chain.length > AnatomyResourceLimits.referenceDepth) { + diagnostics.push({ + code: "resource_limit_exceeded", + message: "Reference depth exceeded", + chain, + }); + return 0; + } + if (active.has(key)) { + diagnostics.push({ + code: "composition_cycle", + message: `Composition cycle reaches ${key}`, + chain, + }); + return 0; + } + if (heights.has(key)) return heights.get(key)!; + active.add(key); + let height = 0; + for (const edge of edges.get(key) ?? []) { + if (!definitions.has(edge.ref)) + diagnostics.push({ + code: "unavailable_reference", + message: `Unavailable reference ${edge.ref}`, + origin: edge.origin, + chain: [...chain, edge.origin], + }); + else + height = Math.max( + height, + 1 + visitGraph(edge.ref, [...chain, edge.origin]), + ); + } + active.delete(key); + heights.set(key, height); + return height; + }; + if (visitGraph(bundle.root, []) > AnatomyResourceLimits.referenceDepth) + diagnostics.push({ + code: "resource_limit_exceeded", + message: "Reference depth exceeded", + }); + if (diagnostics.length) return err(diagnostics); + const compiled = new Map( + [...definitions].map(([key, definition]) => [ + key, + compileAnatomyDefinition( + key, + definition, + definitions, + ( + input as { definitions: { key: string; definition: unknown }[] } + ).definitions.find((item) => item.key === key)?.definition, + ), + ]), + ); + for (const [key, definition] of compiled) { + // Unreachable missing references are not executable; only compile their locally defined shape. + const validation = validateAnatomyForPublish(definition.compiledDefinition); + const registry = anatomyRulePaths(definition.compiledDefinition); + if (validation.isErr()) + for (const issue of validation.error.filter((issue) => { + if (issue.code !== "duplicate_literal_name") return true; + const node = registry.get(issue.nodeId)?.node; + const parent = issue.parentId + ? registry.get(issue.parentId)?.node + : undefined; + const siblings = !parent + ? definition.compiledDefinition.structure.root.children + : parent.kind === "one_of" + ? parent.alternatives + : parent.kind === "directory" + ? parent.children + : []; + const same = siblings.filter( + (sibling) => + node && + node.kind !== "one_of" && + sibling.kind !== "one_of" && + sibling.name.value === node.name.value, + ); + return ( + !same.some((sibling) => definition.mounts.has(sibling.id)) || + same.filter((sibling) => !definition.mounts.has(sibling.id)).length > + 1 + ); + })) + diagnostics.push({ + code: "invalid_bundle", + message: issue.message, + origin: definition.origins.get(issue.nodeId) ?? { + definitionKey: key, + rulePath: "/structure", + sourceNodeId: null, + }, + }); + } + if (diagnostics.length) return err(diagnostics); + return ok({ bundle, compiled }); +}; +export type ResolvedAnatomyBundle = + ReturnType extends import("neverthrow").Result< + infer T, + unknown + > + ? T + : never; diff --git a/packages/anatomy/src/composition/scanAnatomy.ts b/packages/anatomy/src/composition/scanAnatomy.ts new file mode 100644 index 0000000..6671914 --- /dev/null +++ b/packages/anatomy/src/composition/scanAnatomy.ts @@ -0,0 +1,102 @@ +import type { + AnatomyScanOutcome, + AnatomySourceExports, +} from "@anatomy-cli/schemas"; +import { ResultAsync } from "neverthrow"; +import { planAnatomyBundle } from "./planAnatomyBundle.js"; +import { applyAnatomyExportChecks } from "../core/applyAnatomyExportChecks.js"; + +export const scanAnatomy = async ( + input: unknown, +): Promise => { + const planned = planAnatomyBundle(input); + if (planned.isErr()) + return { + operation: "check", + status: "error", + conforms: null, + diagnostics: planned.error, + }; + const { issues, exports, sources } = planned.value; + const analyzed = new Map(); + if (exports.length) { + const analyzer = await ResultAsync.fromPromise( + import("../source/analyzeSourceExports.js"), + () => ({ + code: "source_analysis_error" as const, + message: "Unable to load source analyzer", + }), + ); + if (analyzer.isErr()) + return { + operation: "check", + status: "error", + conforms: null, + diagnostics: [analyzer.error], + }; + for (const { check, finding } of exports) { + if (!analyzed.has(check.path)) { + const source = sources[check.path]; + if (source === undefined) + return { + operation: "check", + status: "error", + conforms: null, + diagnostics: [ + { + code: "source_unavailable", + message: "Source text required for export rule", + entryPath: check.path, + }, + ], + }; + const result = analyzer.value.analyzeSourceExports(check.path, source); + if (result.isErr()) + return { + operation: "check", + status: "error", + conforms: null, + diagnostics: [ + { + code: "source_analysis_error", + message: result.error.message, + entryPath: check.path, + }, + ], + }; + analyzed.set(check.path, result.value); + } + const checked = applyAnatomyExportChecks( + { + issues: [], + summary: { block: 0, warn: 0, allow: 0 }, + conforms: true, + }, + [check], + analyzed, + ); + if (checked.isErr()) + return { + operation: "check", + status: "error", + conforms: null, + diagnostics: [ + { code: "source_analysis_error", message: checked.error.message }, + ], + }; + issues.push(...checked.value.issues.map(finding)); + } + } + issues.sort((a, b) => + a.issueKey < b.issueKey ? -1 : a.issueKey > b.issueKey ? 1 : 0, + ); + const summary = { block: 0, warn: 0, allow: 0 }; + for (const issue of issues) summary[issue.severity]++; + return { + operation: "check", + status: "completed", + conforms: summary.block === 0, + summary, + issues, + }; +}; diff --git a/packages/anatomy/src/composition/validateAnatomyBundle.ts b/packages/anatomy/src/composition/validateAnatomyBundle.ts new file mode 100644 index 0000000..28f0ba8 --- /dev/null +++ b/packages/anatomy/src/composition/validateAnatomyBundle.ts @@ -0,0 +1,10 @@ +import type { AnatomyBundleValidationOutcome } from "@anatomy-cli/schemas"; +import { resolveAnatomyBundle } from "./resolveAnatomyBundle.js"; +export const validateAnatomyBundle = ( + input: unknown, +): AnatomyBundleValidationOutcome => { + const resolved = resolveAnatomyBundle(input); + return resolved.isErr() + ? { status: "error", diagnostics: resolved.error } + : { status: "valid", bundle: resolved.value.bundle }; +}; diff --git a/packages/anatomy/src/core/anatomy-tree.spec.ts b/packages/anatomy/src/core/anatomy-tree.spec.ts index 6976edd..32bea42 100644 --- a/packages/anatomy/src/core/anatomy-tree.spec.ts +++ b/packages/anatomy/src/core/anatomy-tree.spec.ts @@ -1,19 +1,19 @@ import { describe, expect, it } from "vitest"; -import { createDirectoryEntry } from "./createDirectoryEntry"; -import { createEmptyStructure } from "./createEmptyStructure"; -import { createFileEntry } from "./createFileEntry"; -import { groupSiblingEntries } from "./groupSiblingEntries"; -import { insertAnatomyNode } from "./insertAnatomyNode"; -import { locateNodeInTree } from "./locateNodeInTree"; -import { removeAnatomyNode } from "./removeAnatomyNode"; -import { updateAnatomyNode } from "./updateAnatomyNode"; +import { createDirectoryEntry } from "./createDirectoryEntry.js"; +import { createEmptyStructure } from "./createEmptyStructure.js"; +import { createFileEntry } from "./createFileEntry.js"; +import { groupSiblingEntries } from "./groupSiblingEntries.js"; +import { insertAnatomyNode } from "./insertAnatomyNode.js"; +import { locateNodeInTree } from "./locateNodeInTree.js"; +import { removeAnatomyNode } from "./removeAnatomyNode.js"; +import { updateAnatomyNode } from "./updateAnatomyNode.js"; describe("anatomy-tree", () => { describe("createEmptyStructure", () => { it("returns a valid empty structure", () => { const structure = createEmptyStructure(); - expect(structure.schemaVersion).toBe(1); + expect(structure.rootMode).toBe("contents"); expect(structure.root.children).toEqual([]); expect(structure.defaultPolicies.missingRequired).toBe("block"); }); diff --git a/packages/anatomy/src/core/applyAnatomyExportChecks.ts b/packages/anatomy/src/core/applyAnatomyExportChecks.ts new file mode 100644 index 0000000..a7f744d --- /dev/null +++ b/packages/anatomy/src/core/applyAnatomyExportChecks.ts @@ -0,0 +1,62 @@ +import type { + AnatomyFunctionExportCheck, + AnatomySourceExports, +} from "@anatomy-cli/schemas"; +import { err, ok } from "neverthrow"; +import { AnatomyCheckCode } from "./AnatomyCheckCode.js"; +import { AnatomySourceAnalysisError } from "./AnatomySourceAnalysisError.js"; +import type { + AnatomyCheckIssue, + AnatomyCheckResult, +} from "./planAnatomyCheck.js"; + +export const applyAnatomyExportChecks = ( + structuralResult: AnatomyCheckResult, + exportChecks: AnatomyFunctionExportCheck[], + sourceExports: ReadonlyMap, +) => { + for (const check of exportChecks) { + const actual = sourceExports.get(check.path); + if (actual === undefined) + return err( + new AnatomySourceAnalysisError( + check.path, + `Exports were not analyzed for ${check.path}`, + ), + ); + const addIssue = (code: AnatomyCheckIssue["code"], message: string) => { + structuralResult.issues.push({ + code, + message, + severity: check.policy, + path: check.path, + constraintId: check.constraintId, + expectedExport: check.expectedName, + actualExports: actual, + }); + structuralResult.summary[check.policy] += 1; + }; + if (actual.length !== 1) { + addIssue( + AnatomyCheckCode.exportCountMismatch, + `Expected exactly one named function export "${check.expectedName}" but found ${actual.length} runtime exports`, + ); + continue; + } + const exported = actual[0]!; + if (exported.name === "default" || exported.name !== check.expectedName) { + addIssue( + AnatomyCheckCode.exportNameMismatch, + `Expected named export "${check.expectedName}" but found "${exported.name}"`, + ); + } + if (exported.kind !== "function") { + addIssue( + AnatomyCheckCode.exportKindMismatch, + `Expected function export "${check.expectedName}" but found a non-function value`, + ); + } + } + structuralResult.conforms = structuralResult.summary.block === 0; + return ok(structuralResult); +}; diff --git a/packages/anatomy/src/core/check-anatomy.spec.ts b/packages/anatomy/src/core/check-anatomy.spec.ts index 2524afb..eab0aae 100644 --- a/packages/anatomy/src/core/check-anatomy.spec.ts +++ b/packages/anatomy/src/core/check-anatomy.spec.ts @@ -1,10 +1,10 @@ import { type AnatomyDraftInput } from "@anatomy-cli/schemas"; import { describe, expect, it } from "vitest"; -import { AnatomyCheckCode } from "./AnatomyCheckCode"; -import { AnatomyValidationCode } from "./AnatomyValidationCode"; -import { checkAnatomy } from "./checkAnatomy"; -import { createEmptyAnatomyDraft } from "./createEmptyAnatomyDraft"; -import { type AnatomyFileTreeEntry } from "./planAnatomyCheck"; +import { AnatomyCheckCode } from "./AnatomyCheckCode.js"; +import { AnatomyValidationCode } from "./AnatomyValidationCode.js"; +import { checkAnatomy } from "./checkAnatomy.js"; +import { createEmptyAnatomyDraft } from "./createEmptyAnatomyDraft.js"; +import { type AnatomyFileTreeEntry } from "./planAnatomyCheck.js"; const file = (id: string, name: string, quantity = "exactly_one" as const) => { return { diff --git a/packages/anatomy/src/core/checkAnatomy.ts b/packages/anatomy/src/core/checkAnatomy.ts index dec3183..da08f43 100644 --- a/packages/anatomy/src/core/checkAnatomy.ts +++ b/packages/anatomy/src/core/checkAnatomy.ts @@ -1,44 +1,31 @@ import { -type AnatomyDraftInput, -type AnatomySourceExports + type AnatomyDraftInput, + type AnatomySourceExports, } from "@anatomy-cli/schemas"; -import { err, ok, type Result as ResultType } from "neverthrow"; -import { AnatomyCheckCode } from "./AnatomyCheckCode"; -import { AnatomySourceAnalysisError } from "./AnatomySourceAnalysisError"; -import { planAnatomyCheck, type AnatomyCheckIssue, type AnatomyCheckResult, type AnatomyFileTreeEntry } from "./planAnatomyCheck"; -import { type AnatomyValidationIssue } from "./validateAnatomyForPublish"; +import { err, type Result as ResultType } from "neverthrow"; +import { applyAnatomyExportChecks } from "./applyAnatomyExportChecks.js"; +import { AnatomySourceAnalysisError } from "./AnatomySourceAnalysisError.js"; +import { + planAnatomyCheck, + type AnatomyCheckResult, + type AnatomyFileTreeEntry, +} from "./planAnatomyCheck.js"; +import { type AnatomyValidationIssue } from "./validateAnatomyForPublish.js"; export const checkAnatomy = ( definition: AnatomyDraftInput, entries: AnatomyFileTreeEntry[], sourceExports: ReadonlyMap = new Map(), -): ResultType => { +): ResultType< + AnatomyCheckResult, + AnatomyValidationIssue[] | AnatomySourceAnalysisError +> => { const plan = planAnatomyCheck(definition, entries); if (plan.isErr()) return err(plan.error); const { structuralResult, exportChecks } = plan.value; - for (const check of exportChecks) { - const actual = sourceExports.get(check.path); - if (actual === undefined) return err(new AnatomySourceAnalysisError(check.path, `Exports were not analyzed for ${check.path}`)); - const addIssue = (code: AnatomyCheckIssue["code"], message: string) => { - structuralResult.issues.push({ - code, message, severity: check.policy, path: check.path, constraintId: check.constraintId, - expectedExport: check.expectedName, actualExports: actual, - }); - structuralResult.summary[check.policy] += 1; - }; - if (actual.length !== 1) { - addIssue(AnatomyCheckCode.exportCountMismatch, - `Expected exactly one named function export "${check.expectedName}" but found ${actual.length} runtime exports`); - continue; - } - const exported = actual[0]!; - if (exported.name === "default" || exported.name !== check.expectedName) { - addIssue(AnatomyCheckCode.exportNameMismatch, `Expected named export "${check.expectedName}" but found "${exported.name}"`); - } - if (exported.kind !== "function") { - addIssue(AnatomyCheckCode.exportKindMismatch, `Expected function export "${check.expectedName}" but found a non-function value`); - } - } - structuralResult.conforms = structuralResult.summary.block === 0; - return ok(structuralResult); + return applyAnatomyExportChecks( + structuralResult, + exportChecks, + sourceExports, + ); }; diff --git a/packages/anatomy/src/core/createDirectoryEntry.ts b/packages/anatomy/src/core/createDirectoryEntry.ts index d2e0329..714b0b5 100644 --- a/packages/anatomy/src/core/createDirectoryEntry.ts +++ b/packages/anatomy/src/core/createDirectoryEntry.ts @@ -1,5 +1,5 @@ import type { AnatomyEntry, AnatomyNode, AnatomyQuantity } from "@anatomy-cli/schemas"; -import { uid } from "./uid"; +import { uid } from "./uid.js"; export const createDirectoryEntry = ( name: string, diff --git a/packages/anatomy/src/core/createEmptyAnatomyDraft.ts b/packages/anatomy/src/core/createEmptyAnatomyDraft.ts index 66f9179..7fdf18e 100644 --- a/packages/anatomy/src/core/createEmptyAnatomyDraft.ts +++ b/packages/anatomy/src/core/createEmptyAnatomyDraft.ts @@ -5,7 +5,7 @@ export const createEmptyAnatomyDraft = (name: string, purpose: string): AnatomyD name, purpose, structure: { - schemaVersion: 1, + rootMode: "contents", defaultPolicies: { missingRequired: "block", unexpectedEntry: "warn", diff --git a/packages/anatomy/src/core/createEmptyStructure.ts b/packages/anatomy/src/core/createEmptyStructure.ts index c8c1b45..6f2385f 100644 --- a/packages/anatomy/src/core/createEmptyStructure.ts +++ b/packages/anatomy/src/core/createEmptyStructure.ts @@ -2,7 +2,7 @@ import type { AnatomyStructure } from "@anatomy-cli/schemas"; export const createEmptyStructure = (): AnatomyStructure => { return { - schemaVersion: 1, + rootMode: "contents", defaultPolicies: { missingRequired: "block", unexpectedEntry: "warn", diff --git a/packages/anatomy/src/core/createFileEntry.ts b/packages/anatomy/src/core/createFileEntry.ts index 4b4d5e9..add5908 100644 --- a/packages/anatomy/src/core/createFileEntry.ts +++ b/packages/anatomy/src/core/createFileEntry.ts @@ -1,5 +1,5 @@ import type { AnatomyEntry, AnatomyQuantity } from "@anatomy-cli/schemas"; -import { uid } from "./uid"; +import { uid } from "./uid.js"; export const createFileEntry = ( name: string, diff --git a/packages/anatomy/src/core/findNodeInTree.ts b/packages/anatomy/src/core/findNodeInTree.ts index ff1086b..2984484 100644 --- a/packages/anatomy/src/core/findNodeInTree.ts +++ b/packages/anatomy/src/core/findNodeInTree.ts @@ -1,5 +1,5 @@ import type { AnatomyEntry, AnatomyNode } from "@anatomy-cli/schemas"; -import { type TreeNodeParent, locateNodeInTree } from "./locateNodeInTree"; +import { type TreeNodeParent, locateNodeInTree } from "./locateNodeInTree.js"; type TreeNodeResult = { found: true; parent: TreeNodeParent; index: number } | { found: false }; diff --git a/packages/anatomy/src/core/function-export.spec.ts b/packages/anatomy/src/core/function-export.spec.ts index 6d03178..1a3105e 100644 --- a/packages/anatomy/src/core/function-export.spec.ts +++ b/packages/anatomy/src/core/function-export.spec.ts @@ -1,13 +1,13 @@ import { AnatomyDraftInputSchema, type AnatomySourceExports } from "@anatomy-cli/schemas"; import { describe, expect, it } from "vitest"; -import { checkAnatomy } from "./checkAnatomy"; -import { planAnatomyCheck } from "./planAnatomyCheck"; -import { queryAnatomy } from "./queryAnatomy"; +import { checkAnatomy } from "./checkAnatomy.js"; +import { planAnatomyCheck } from "./planAnatomyCheck.js"; +import { queryAnatomy } from "./queryAnatomy.js"; const definition = () => AnatomyDraftInputSchema.parse({ name: "Function files", purpose: "One named function per file", structure: { - schemaVersion: 1, + rootMode: "contents", defaultPolicies: { missingRequired: "block", unexpectedEntry: "block", nameMismatch: "block", nestingMismatch: "block" }, root: { children: [{ kind: "file", name: { type: "placeholder", value: ".ts" }, quantity: "one_or_more", diff --git a/packages/anatomy/src/core/groupSiblingEntries.ts b/packages/anatomy/src/core/groupSiblingEntries.ts index a4a3a02..5a1a6b1 100644 --- a/packages/anatomy/src/core/groupSiblingEntries.ts +++ b/packages/anatomy/src/core/groupSiblingEntries.ts @@ -1,8 +1,8 @@ import type { AnatomyEntry, AnatomyNode, AnatomyStructure } from "@anatomy-cli/schemas"; -import { cloneEntry } from "./cloneEntry"; -import { locateNodeInTree } from "./locateNodeInTree"; -import { replaceNodeInTree } from "./replaceNodeInTree"; -import { uid } from "./uid"; +import { cloneEntry } from "./cloneEntry.js"; +import { locateNodeInTree } from "./locateNodeInTree.js"; +import { replaceNodeInTree } from "./replaceNodeInTree.js"; +import { uid } from "./uid.js"; export const groupSiblingEntries = ( root: AnatomyStructure, diff --git a/packages/anatomy/src/core/index.ts b/packages/anatomy/src/core/index.ts index 8a4ce43..5e34d90 100644 --- a/packages/anatomy/src/core/index.ts +++ b/packages/anatomy/src/core/index.ts @@ -1,23 +1,23 @@ -export * from "./resolveAnatomyExportName"; -export * from "./anatomyRulePaths"; -export * from "./AnatomyCheckCode"; -export * from "./AnatomyQueryPathError"; -export * from "./AnatomySourceAnalysisError"; -export * from "./AnatomyValidationCode"; -export * from "./checkAnatomy"; -export * from "./createDirectoryEntry"; -export * from "./createEmptyAnatomyDraft"; -export * from "./createEmptyStructure"; -export * from "./createFileEntry"; -export * from "./findNodeInTree"; -export * from "./groupSiblingEntries"; -export * from "./insertAnatomyNode"; -export * from "./locateNodeInTree"; -export * from "./evaluateName"; -export * from "./planAnatomyCheck"; -export * from "./queryAnatomy"; -export * from "./removeAnatomyNode"; -export * from "./resolveAnatomyPolicies"; -export * from "./ResolvedAnatomyPolicy"; -export * from "./updateAnatomyNode"; -export * from "./validateAnatomyForPublish"; +export * from "./resolveAnatomyExportName.js"; +export * from "./anatomyRulePaths.js"; +export * from "./AnatomyCheckCode.js"; +export * from "./AnatomyQueryPathError.js"; +export * from "./AnatomySourceAnalysisError.js"; +export * from "./AnatomyValidationCode.js"; +export * from "./checkAnatomy.js"; +export * from "./createDirectoryEntry.js"; +export * from "./createEmptyAnatomyDraft.js"; +export * from "./createEmptyStructure.js"; +export * from "./createFileEntry.js"; +export * from "./findNodeInTree.js"; +export * from "./groupSiblingEntries.js"; +export * from "./insertAnatomyNode.js"; +export * from "./locateNodeInTree.js"; +export * from "./evaluateName.js"; +export * from "./planAnatomyCheck.js"; +export * from "./queryAnatomy.js"; +export * from "./removeAnatomyNode.js"; +export * from "./resolveAnatomyPolicies.js"; +export * from "./ResolvedAnatomyPolicy.js"; +export * from "./updateAnatomyNode.js"; +export * from "./validateAnatomyForPublish.js"; diff --git a/packages/anatomy/src/core/insertAnatomyNode.ts b/packages/anatomy/src/core/insertAnatomyNode.ts index 548b569..2b4e520 100644 --- a/packages/anatomy/src/core/insertAnatomyNode.ts +++ b/packages/anatomy/src/core/insertAnatomyNode.ts @@ -1,7 +1,7 @@ import type { AnatomyNode, AnatomyStructure } from "@anatomy-cli/schemas"; -import { cloneEntry } from "./cloneEntry"; -import { locateNodeInTree } from "./locateNodeInTree"; -import { replaceNodeInTree } from "./replaceNodeInTree"; +import { cloneEntry } from "./cloneEntry.js"; +import { locateNodeInTree } from "./locateNodeInTree.js"; +import { replaceNodeInTree } from "./replaceNodeInTree.js"; export const insertAnatomyNode = ( root: AnatomyStructure, diff --git a/packages/anatomy/src/core/planAnatomyCheck.ts b/packages/anatomy/src/core/planAnatomyCheck.ts index d265b8a..befdcf3 100644 --- a/packages/anatomy/src/core/planAnatomyCheck.ts +++ b/packages/anatomy/src/core/planAnatomyCheck.ts @@ -1,18 +1,25 @@ import { -type AnatomyDraftInput, -type AnatomyEntry, -type AnatomyFunctionExportCheck, -type AnatomyNode, -type AnatomyPolicies, -type AnatomyPolicyOverrides, -type AnatomySourceExports, + type AnatomyDraftInput, + type AnatomyEntry, + type AnatomyFunctionExportCheck, + type AnatomyNode, + type AnatomyPolicies, + type AnatomyPolicyOverrides, + type AnatomySourceExports, } from "@anatomy-cli/schemas"; import { err, ok, type Result as ResultType } from "neverthrow"; -import { resolveAnatomyExportName } from "./resolveAnatomyExportName"; -import { AnatomyCheckCode } from "./AnatomyCheckCode"; -import { evaluateName, type BindingScope, type NameMatch } from "./evaluateName"; -import { resolveAnatomyPolicies } from "./resolveAnatomyPolicies"; -import { validateAnatomyForPublish, type AnatomyValidationIssue } from "./validateAnatomyForPublish"; +import { resolveAnatomyExportName } from "./resolveAnatomyExportName.js"; +import { AnatomyCheckCode } from "./AnatomyCheckCode.js"; +import { + evaluateName, + type BindingScope, + type NameMatch, +} from "./evaluateName.js"; +import { resolveAnatomyPolicies } from "./resolveAnatomyPolicies.js"; +import { + validateAnatomyForPublish, + type AnatomyValidationIssue, +} from "./validateAnatomyForPublish.js"; export type AnatomyFileTreeEntry = | { kind: "file"; name: string } @@ -78,7 +85,7 @@ const getQuantityRange = ( } }; -const getPolicy = ( +const resolvePolicyValue = ( defaults: AnatomyPolicies, ancestors: PolicyAncestor[], key: keyof AnatomyPolicies, @@ -95,22 +102,60 @@ const getEntryLabel = (entry: AnatomyEntry): string => { return entry.name.value; }; +export type AnatomyPlanHooks = { + skipValidation?: boolean; + onDirectory?: ( + entry: Extract, + actual: Extract, + path: string, + scope: BindingScope, + ) => boolean; + onLevel?: ( + nodes: AnatomyNode[], + entries: AnatomyFileTreeEntry[], + path: string, + scope: BindingScope, + ) => boolean; + onIssue?: ( + issue: AnatomyCheckIssue, + context: { + parentPath: string; + ancestors: PolicyAncestor[]; + scope: BindingScope; + policyKey: keyof AnatomyPolicies; + }, + ) => void; + onMatch?: (entry: AnatomyEntry, path: string, scope: BindingScope) => void; + matchName?: ( + entry: AnatomyEntry, + name: string, + scope: BindingScope, + ignoreCase: boolean, + ) => NameMatch; + preferKindOwner?: boolean; +}; + export const planAnatomyCheck = ( definition: AnatomyDraftInput, entries: AnatomyFileTreeEntry[], -): ResultType<{ structuralResult: AnatomyCheckResult; exportChecks: AnatomyFunctionExportCheck[] }, AnatomyValidationIssue[]> => { - const validated = validateAnatomyForPublish(definition); - if (validated.isErr()) return err(validated.error); + hooks: AnatomyPlanHooks = {}, +): ResultType< + { + structuralResult: AnatomyCheckResult; + exportChecks: AnatomyFunctionExportCheck[]; + }, + AnatomyValidationIssue[] +> => { + if (!hooks.skipValidation) { + const validated = validateAnatomyForPublish(definition); + if (validated.isErr()) return err(validated.error); + } const issues: AnatomyCheckIssue[] = []; const exportChecks: AnatomyFunctionExportCheck[] = []; const defaults = definition.structure.defaultPolicies; const bindings = definition.structure.bindings ?? {}; - const addIssue = (issue: AnatomyCheckIssue): void => { - issues.push(issue); - }; - const checkNodes = ( expectedNodes: AnatomyNode[], actualEntries: AnatomyFileTreeEntry[], @@ -118,10 +163,33 @@ export const planAnatomyCheck = ( ancestors: PolicyAncestor[], scope: BindingScope, ): void => { + if ( + hooks.onLevel?.(expectedNodes, actualEntries, parentPath, scope) === false + ) + return; + let policyKey: keyof AnatomyPolicies = "unexpectedEntry"; + const getPolicy = (...args: Parameters) => { + policyKey = args[2]; + return resolvePolicyValue(...args); + }; + const addIssue = (issue: AnatomyCheckIssue): void => { + issues.push(issue); + hooks.onIssue?.(issue, { parentPath, ancestors, scope, policyKey }); + }; + const matchName = ( + entry: AnatomyEntry, + name: string, + ignoreCase = false, + ) => + hooks.matchName + ? hooks.matchName(entry, name, scope, ignoreCase) + : evaluateName(entry, name, scope, bindings, ignoreCase); const consumed = new Set(); const availableIndexes = (): number[] => { - return actualEntries.flatMap((_, index) => (consumed.has(index) ? [] : [index])); + return actualEntries.flatMap((_, index) => + consumed.has(index) ? [] : [index], + ); }; const findMatches = ( @@ -135,18 +203,38 @@ export const planAnatomyCheck = ( return []; } - const match = evaluateName(entry, actual.name, scope, bindings, options.ignoreCase); + if ( + hooks.preferKindOwner && + actual.kind !== entry.kind && + expectedNodes.some((node) => { + const choices = node.kind === "one_of" ? node.alternatives : [node]; + return choices.some( + (other) => + other.id !== entry.id && + other.kind === actual.kind && + (matchName(other, actual.name).kind !== "none" || + matchName(other, actual.name, true).kind !== "none"), + ); + }) + ) + return []; + const match = matchName(entry, actual.name, options.ignoreCase); return match.kind === "none" ? [] : [{ index, match }]; }); }; - const checkEntry = (entry: AnatomyEntry, suppressMissing: boolean): number => { + const checkEntry = ( + entry: AnatomyEntry, + suppressMissing: boolean, + ): number => { const structuralCandidates = findMatches(entry, { requireKind: false }); - const nestingMismatchCandidates = structuralCandidates.filter((candidate) => { - const actual = actualEntries[candidate.index]; + const nestingMismatchCandidates = structuralCandidates.filter( + (candidate) => { + const actual = actualEntries[candidate.index]; - return actual !== undefined && actual.kind !== entry.kind; - }); + return actual !== undefined && actual.kind !== entry.kind; + }, + ); for (const candidate of nestingMismatchCandidates) { const actual = actualEntries[candidate.index]; if (!actual) continue; @@ -164,14 +252,22 @@ export const planAnatomyCheck = ( (candidate): candidate is SuccessfulNameMatchCandidate => { const actual = actualEntries[candidate.index]; - return actual?.kind === entry.kind && candidate.match.kind === "match"; + return ( + actual?.kind === entry.kind && candidate.match.kind === "match" + ); }, ); - const bindingMismatchCandidates = structuralCandidates.filter((candidate): candidate is NameMatchCandidate & { match: BindingMismatch } => { - const actual = actualEntries[candidate.index]; + const bindingMismatchCandidates = structuralCandidates.filter( + ( + candidate, + ): candidate is NameMatchCandidate & { match: BindingMismatch } => { + const actual = actualEntries[candidate.index]; - return actual?.kind === entry.kind && candidate.match.kind !== "match"; - }); + return ( + actual?.kind === entry.kind && candidate.match.kind !== "match" + ); + }, + ); for (const candidate of bindingMismatchCandidates) { const actual = actualEntries[candidate.index]; if (!actual) continue; @@ -205,9 +301,15 @@ export const planAnatomyCheck = ( } } - const correctIndexes = correctCandidates.map((candidate) => candidate.index); - const caseInsensitiveCandidates = findMatches(entry, { ignoreCase: true }); - const caseInsensitiveIndexes = caseInsensitiveCandidates.map((candidate) => candidate.index); + const correctIndexes = correctCandidates.map( + (candidate) => candidate.index, + ); + const caseInsensitiveCandidates = findMatches(entry, { + ignoreCase: true, + }); + const caseInsensitiveIndexes = caseInsensitiveCandidates.map( + (candidate) => candidate.index, + ); const nameMismatchIndexes = caseInsensitiveIndexes.filter( (index) => !correctIndexes.includes(index), ); @@ -255,22 +357,40 @@ export const planAnatomyCheck = ( }); } + const childScope = { ...scope, ...candidate.match.captures }; + hooks.onMatch?.(entry, joinPath(parentPath, actual.name), childScope); if (entry.kind === "file" && actual.kind === "file" && entry.exports) { exportChecks.push({ - path: joinPath(parentPath, actual.name), constraintId: entry.id, - expectedName: resolveAnatomyExportName(entry.exports, actual.name, { ...scope, ...candidate.match.captures }), + path: joinPath(parentPath, actual.name), + constraintId: entry.id, + expectedName: resolveAnatomyExportName(entry.exports, actual.name, { + ...scope, + ...candidate.match.captures, + }), policy: entry.exports.policy, }); } if (entry.kind === "directory" && actual.kind === "directory") { - checkNodes(entry.children, actual.children, joinPath(parentPath, actual.name), [ - ...ancestors, - { id: entry.id, overrides: entry.policyOverrides }, - ], { - ...scope, - ...candidate.match.captures, - }); + if ( + hooks.onDirectory?.( + entry, + actual, + joinPath(parentPath, actual.name), + childScope, + ) === false + ) + continue; + checkNodes( + entry.children, + actual.children, + joinPath(parentPath, actual.name), + [...ancestors, { id: entry.id, overrides: entry.policyOverrides }], + { + ...scope, + ...candidate.match.captures, + }, + ); } } @@ -291,7 +411,9 @@ export const planAnatomyCheck = ( matchedAlternatives.length > node.maximumMatches ) { const policyKey = - matchedAlternatives.length < node.minimumMatches ? "missingRequired" : "unexpectedEntry"; + matchedAlternatives.length < node.minimumMatches + ? "missingRequired" + : "unexpectedEntry"; addIssue({ code: AnatomyCheckCode.oneOfMismatch, severity: getPolicy(defaults, ancestors, policyKey), @@ -329,5 +451,8 @@ export const planAnatomyCheck = ( { block: 0, warn: 0, allow: 0 }, ); - return ok({ structuralResult: { issues, summary, conforms: summary.block === 0 }, exportChecks }); + return ok({ + structuralResult: { issues, summary, conforms: summary.block === 0 }, + exportChecks, + }); }; diff --git a/packages/anatomy/src/core/query-anatomy.spec.ts b/packages/anatomy/src/core/query-anatomy.spec.ts index 76f2188..a6f831e 100644 --- a/packages/anatomy/src/core/query-anatomy.spec.ts +++ b/packages/anatomy/src/core/query-anatomy.spec.ts @@ -1,13 +1,13 @@ import { AnatomyDraftInputSchema, AnatomyQueryWithConstraintsSchema } from "@anatomy-cli/schemas"; import { describe, expect, it } from "vitest"; -import { anatomyRulePaths } from "./anatomyRulePaths"; -import { checkAnatomy } from "./checkAnatomy"; -import { queryAnatomy } from "./queryAnatomy"; +import { anatomyRulePaths } from "./anatomyRulePaths.js"; +import { checkAnatomy } from "./checkAnatomy.js"; +import { queryAnatomy } from "./queryAnatomy.js"; const serviceDefinition = () => AnatomyDraftInputSchema.parse({ name: "Services", purpose: "Agent workflow", structure: { - schemaVersion: 1, + rootMode: "contents", defaultPolicies: { missingRequired: "block", unexpectedEntry: "warn", nameMismatch: "block", nestingMismatch: "block" }, bindings: { Name: { format: "PascalCase", pattern: "[A-Z][a-z]+" } }, root: { children: [{ diff --git a/packages/anatomy/src/core/queryAnatomy.ts b/packages/anatomy/src/core/queryAnatomy.ts index 628df83..097cc2a 100644 --- a/packages/anatomy/src/core/queryAnatomy.ts +++ b/packages/anatomy/src/core/queryAnatomy.ts @@ -1,38 +1,72 @@ -import { AnatomyQueryWithConstraintsSchema, type AnatomyDraftInput, type AnatomyNode, type AnatomyQueryWithConstraints } from "@anatomy-cli/schemas"; +import { + AnatomyQueryWithConstraintsSchema, + type AnatomyDraftInput, + type AnatomyNode, + type AnatomyQueryWithConstraints, +} from "@anatomy-cli/schemas"; import { err, ok, type Result } from "neverthrow"; -import { resolveAnatomyExportName } from "./resolveAnatomyExportName"; -import { anatomyRulePaths } from "./anatomyRulePaths"; -import { AnatomyQueryPathError } from "./AnatomyQueryPathError"; -import { evaluateName } from "./evaluateName"; -import { resolveAnatomyPolicies } from "./resolveAnatomyPolicies"; -import { validateAnatomyForPublish, type AnatomyValidationIssue } from "./validateAnatomyForPublish"; +import { resolveAnatomyExportName } from "./resolveAnatomyExportName.js"; +import { anatomyRulePaths } from "./anatomyRulePaths.js"; +import { AnatomyQueryPathError } from "./AnatomyQueryPathError.js"; +import { evaluateName } from "./evaluateName.js"; +import { resolveAnatomyPolicies } from "./resolveAnatomyPolicies.js"; +import { + validateAnatomyForPublish, + type AnatomyValidationIssue, +} from "./validateAnatomyForPublish.js"; const QueryStatus = AnatomyQueryWithConstraintsSchema.shape.status.enum; export const queryAnatomy = ( definition: AnatomyDraftInput, path: string, -): Result => { + hooks: { skipValidation?: boolean; matchName?: typeof evaluateName } = {}, +): Result< + AnatomyQueryWithConstraints, + AnatomyValidationIssue[] | AnatomyQueryPathError +> => { const normalized = path.replaceAll("\\", "/"); - if (!path || normalized.startsWith("/") || /^[A-Za-z]:/.test(normalized) || - normalized.split("/").includes("..") || normalized.includes("\0")) { + if ( + !path || + normalized.startsWith("/") || + /^[A-Za-z]:/.test(normalized) || + normalized.split("/").includes("..") || + normalized.includes("\0") + ) { return err(new AnatomyQueryPathError(path)); } - const validated = validateAnatomyForPublish(definition); - if (validated.isErr()) return err(validated.error); + if (!hooks.skipValidation) { + const validated = validateAnatomyForPublish(definition); + if (validated.isErr()) return err(validated.error); + } + const matchName = hooks.matchName ?? evaluateName; const parts = normalized.split("/").filter((part) => part && part !== "."); const registry = anatomyRulePaths(definition); const defaults = definition.structure.defaultPolicies; const policyAncestors: Parameters[1] = []; const result: AnatomyQueryWithConstraints = { - contractVersion: 1, operation: "query", path: parts.join("/") || ".", scopePath: ".", - status: QueryStatus.resolved, reason: null, captures: {}, bindings: definition.structure.bindings ?? {}, - policies: defaults, ancestors: [], rules: [], matches: [], groups: [], + operation: "query", + path: parts.join("/") || ".", + scopePath: ".", + status: QueryStatus.resolved, + reason: null, + captures: {}, + bindings: definition.structure.bindings ?? {}, + policies: defaults, + ancestors: [], + rules: [], + matches: [], + groups: [], }; const policiesFor = (node?: AnatomyNode) => { - const resolved = resolveAnatomyPolicies(defaults, policyAncestors, - node && node.kind !== "one_of" ? { id: node.id, overrides: node.policyOverrides } : undefined); + const resolved = resolveAnatomyPolicies( + defaults, + policyAncestors, + node && node.kind !== "one_of" + ? { id: node.id, overrides: node.policyOverrides } + : undefined, + ); return { missingRequired: resolved.missingRequired.value, unexpectedEntry: resolved.unexpectedEntry.value, @@ -40,55 +74,94 @@ export const queryAnatomy = ( nestingMismatch: resolved.nestingMismatch.value, }; }; - const describe = (nodes: AnatomyNode[]) => nodes.map((node) => { - const expectedName = node.kind === "one_of" ? null : node.name.type === "literal" ? node.name.value : node.name.value.replace( - /<([^<>]+)>/, (placeholder, name: string) => result.captures[name] ?? placeholder, - ); - return { - rulePath: registry.get(node.id)!.rulePath, node, policies: policiesFor(node), expectedName, - ...(node.kind === "file" && node.exports ? { - expectedExport: resolveAnatomyExportName(node.exports, expectedName!, result.captures), - } : {}), - }; - }); + const describe = (nodes: AnatomyNode[]) => + nodes.map((node) => { + const expectedName = + node.kind === "one_of" + ? null + : node.name.type === "literal" + ? node.name.value + : node.name.value.replace( + /<([^<>]+)>/, + (placeholder, name: string) => + result.captures[name] ?? placeholder, + ); + return { + rulePath: registry.get(node.id)!.rulePath, + node, + policies: policiesFor(node), + expectedName, + ...(node.kind === "file" && node.exports + ? { + expectedExport: resolveAnatomyExportName( + node.exports, + expectedName!, + result.captures, + ), + } + : {}), + }; + }); let nodes = definition.structure.root.children; result.rules = describe(nodes); for (const [index, part] of parts.entries()) { result.policies = policiesFor(); result.rules = describe(nodes); - const entries = nodes.flatMap((node) => node.kind === "one_of" - ? node.alternatives.map((entry) => ({ node: entry, inGroup: true })) - : [{ node, inGroup: false }]); + const entries = nodes.flatMap((node) => + node.kind === "one_of" + ? node.alternatives.map((entry) => ({ node: entry, inGroup: true })) + : [{ node, inGroup: false }], + ); const candidates = entries.flatMap(({ node, inGroup }) => { - const exact = evaluateName(node, part, result.captures, result.bindings); - const match = exact.kind === "none" && !inGroup - ? evaluateName(node, part, result.captures, result.bindings, true) : exact; - return match.kind === "none" ? [] : [{ node, match, caseMismatch: exact.kind === "none" }]; + const exact = matchName(node, part, result.captures, result.bindings); + const match = + exact.kind === "none" && !inGroup + ? matchName(node, part, result.captures, result.bindings, true) + : exact; + return match.kind === "none" + ? [] + : [{ node, match, caseMismatch: exact.kind === "none" }]; }); - result.matches = candidates.map(({ node }) => registry.get(node.id)!.rulePath); + result.matches = candidates.map( + ({ node }) => registry.get(node.id)!.rulePath, + ); if (candidates.length !== 1) { - result.status = candidates.length === 0 ? QueryStatus.unmatched : QueryStatus.ambiguous; - result.reason = candidates.length === 0 - ? `No declared entry matches "${part}" under ${result.scopePath}; the parent's unexpectedEntry policy still applies. Descendants are not checked.` - : `Multiple rules may consume "${part}"; rule order, entry kind and sibling entries affect validation. Inspect the candidates before editing.`; + result.status = + candidates.length === 0 ? QueryStatus.unmatched : QueryStatus.ambiguous; + result.reason = + candidates.length === 0 + ? `No declared entry matches "${part}" under ${result.scopePath}; the parent's unexpectedEntry policy still applies. Descendants are not checked.` + : `Multiple rules may consume "${part}"; rule order, entry kind and sibling entries affect validation. Inspect the candidates before editing.`; return ok(result); } const candidate = candidates[0]!; const { node, match } = candidate; - if (match.kind !== "match" || candidate.caseMismatch || - (index < parts.length - 1 && node.kind !== "directory")) { + if ( + match.kind !== "match" || + candidate.caseMismatch || + (index < parts.length - 1 && node.kind !== "directory") + ) { result.status = QueryStatus.mismatch; - result.reason = candidate.caseMismatch ? "name_mismatch" - : match.kind !== "match" ? match.kind : "nesting_mismatch"; + result.reason = candidate.caseMismatch + ? "name_mismatch" + : match.kind !== "match" + ? match.kind + : "nesting_mismatch"; return ok(result); } for (const group of nodes) { - if (group.kind === "one_of" && group.alternatives.some((entry) => entry.id === node.id)) { + if ( + group.kind === "one_of" && + group.alternatives.some((entry) => entry.id === node.id) + ) { result.groups.push({ rulePath: registry.get(group.id)!.rulePath, - minimumMatches: group.minimumMatches, maximumMatches: group.maximumMatches, - alternatives: group.alternatives.map((entry) => registry.get(entry.id)!.rulePath), + minimumMatches: group.minimumMatches, + maximumMatches: group.maximumMatches, + alternatives: group.alternatives.map( + (entry) => registry.get(entry.id)!.rulePath, + ), }); } } @@ -98,8 +171,10 @@ export const queryAnatomy = ( if (index === parts.length - 1) return ok(result); if (node.kind === "directory") { result.ancestors.push({ - rulePath: registry.get(node.id)!.rulePath, name: part, - quantity: node.quantity, policies: result.policies, + rulePath: registry.get(node.id)!.rulePath, + name: part, + quantity: node.quantity, + policies: result.policies, }); policyAncestors.push({ id: node.id, overrides: node.policyOverrides }); result.scopePath = parts.slice(0, index + 1).join("/"); diff --git a/packages/anatomy/src/core/removeAnatomyNode.ts b/packages/anatomy/src/core/removeAnatomyNode.ts index 7405916..689ff0a 100644 --- a/packages/anatomy/src/core/removeAnatomyNode.ts +++ b/packages/anatomy/src/core/removeAnatomyNode.ts @@ -1,7 +1,7 @@ import type { AnatomyNode, AnatomyStructure } from "@anatomy-cli/schemas"; -import { cloneEntry } from "./cloneEntry"; -import { locateNodeInTree } from "./locateNodeInTree"; -import { replaceNodeInTree } from "./replaceNodeInTree"; +import { cloneEntry } from "./cloneEntry.js"; +import { locateNodeInTree } from "./locateNodeInTree.js"; +import { replaceNodeInTree } from "./replaceNodeInTree.js"; export const removeAnatomyNode = (root: AnatomyStructure, nodeId: string): AnatomyStructure => { const located = locateNodeInTree(root.root.children, nodeId); diff --git a/packages/anatomy/src/core/replaceNodeInTree.ts b/packages/anatomy/src/core/replaceNodeInTree.ts index a9d4031..3559521 100644 --- a/packages/anatomy/src/core/replaceNodeInTree.ts +++ b/packages/anatomy/src/core/replaceNodeInTree.ts @@ -1,5 +1,5 @@ import type { AnatomyNode, AnatomyStructure } from "@anatomy-cli/schemas"; -import { updateAnatomyNode } from "./updateAnatomyNode"; +import { updateAnatomyNode } from "./updateAnatomyNode.js"; export const replaceNodeInTree = ( root: AnatomyStructure, diff --git a/packages/anatomy/src/core/resolveAnatomyPolicies.ts b/packages/anatomy/src/core/resolveAnatomyPolicies.ts index db630ff..7e5aade 100644 --- a/packages/anatomy/src/core/resolveAnatomyPolicies.ts +++ b/packages/anatomy/src/core/resolveAnatomyPolicies.ts @@ -1,5 +1,5 @@ import type { AnatomyPolicies, AnatomyPolicyOverrides } from "@anatomy-cli/schemas"; -import type { ResolvedAnatomyPolicy } from "./ResolvedAnatomyPolicy"; +import type { ResolvedAnatomyPolicy } from "./ResolvedAnatomyPolicy.js"; /** Resolve policies in current-entry, nearest-parent, then Anatomy-default order. */ export const resolveAnatomyPolicies = ( diff --git a/packages/anatomy/src/core/uid.ts b/packages/anatomy/src/core/uid.ts index 7159430..a80a4f0 100644 --- a/packages/anatomy/src/core/uid.ts +++ b/packages/anatomy/src/core/uid.ts @@ -1,6 +1,2 @@ -const state = { counter: 0 }; - -export const uid = (): string => { - state.counter += 1; - return crypto.randomUUID?.() ?? `node-${state.counter}-${Date.now()}`; -}; +import { createAnatomyNodeId } from "@anatomy-cli/schemas"; +export const uid = (): string => createAnatomyNodeId(); diff --git a/packages/anatomy/src/core/validateAnatomyForPublish.ts b/packages/anatomy/src/core/validateAnatomyForPublish.ts index 7539c9a..2c037f7 100644 --- a/packages/anatomy/src/core/validateAnatomyForPublish.ts +++ b/packages/anatomy/src/core/validateAnatomyForPublish.ts @@ -1,6 +1,6 @@ import type { AnatomyDraftInput, AnatomyEntry, AnatomyNode } from "@anatomy-cli/schemas"; import { err, ok, Result, type Result as ResultType } from "neverthrow"; -import { AnatomyValidationCode } from "./AnatomyValidationCode"; +import { AnatomyValidationCode } from "./AnatomyValidationCode.js"; export type AnatomyValidationIssue = { code: (typeof AnatomyValidationCode)[keyof typeof AnatomyValidationCode]; diff --git a/packages/anatomy/src/index.ts b/packages/anatomy/src/index.ts index 8d119de..80d60d1 100644 --- a/packages/anatomy/src/index.ts +++ b/packages/anatomy/src/index.ts @@ -1 +1,2 @@ -export * from "./core"; +export * from "./core/index.js"; +export * from "./composition/index.js"; diff --git a/packages/anatomy/src/source/analyzeSourceExports.ts b/packages/anatomy/src/source/analyzeSourceExports.ts new file mode 100644 index 0000000..58d3331 --- /dev/null +++ b/packages/anatomy/src/source/analyzeSourceExports.ts @@ -0,0 +1,296 @@ +import ts from "typescript"; +import { err, ok, Result, type Result as ResultType } from "neverthrow"; +import { AnatomySourceAnalysisError } from "../core/AnatomySourceAnalysisError.js"; +import type { AnatomySourceExports } from "@anatomy-cli/schemas"; + +const hasModifier = (node: ts.Node, kind: ts.SyntaxKind) => + ts.canHaveModifiers(node) && + ts.getModifiers(node)?.some((modifier) => modifier.kind === kind) === true; + +export const analyzeSourceExports = ( + path: string, + content: string, +): ResultType => { + const fail = (message: string) => + err(new AnatomySourceAnalysisError(path, `${path}: ${message}`)); + if (!/\.(?:[cm]?[jt]s|[jt]sx)$/i.test(path) || /\.d\.[cm]?ts$/i.test(path)) { + return fail( + "Function export checks require a JavaScript or TypeScript implementation file", + ); + } + const parsed = Result.fromThrowable( + () => { + const options: ts.CompilerOptions = { + noLib: true, + noResolve: true, + types: [], + allowJs: true, + target: ts.ScriptTarget.Latest, + }; + const host: ts.CompilerHost = { + getSourceFile: () => undefined, + fileExists: () => false, + readFile: () => undefined, + getDefaultLibFileName: () => "", + writeFile: () => undefined, + getCurrentDirectory: () => "/", + getCanonicalFileName: (name) => name, + useCaseSensitiveFileNames: () => true, + getNewLine: () => "\n", + directoryExists: () => false, + getDirectories: () => [], + realpath: (name) => name, + }; + host.getSourceFile = (filename, languageVersion) => + filename === path + ? ts.createSourceFile(filename, content, languageVersion, true) + : undefined; + host.fileExists = (filename) => filename === path; + host.readFile = (filename) => (filename === path ? content : undefined); + const program = ts.createProgram([path], options, host); + return { + file: program.getSourceFile(path), + diagnostics: program.getSyntacticDiagnostics(), + }; + }, + (cause) => + new AnatomySourceAnalysisError( + path, + `Unable to parse ${path}: ${String(cause)}`, + ), + )(); + if (parsed.isErr()) return err(parsed.error); + const { file, diagnostics } = parsed.value; + if (!file) return fail("Unable to create source file"); + if (diagnostics.length) + return fail( + ts.flattenDiagnosticMessageText(diagnostics[0]!.messageText, "\n"), + ); + + const locals = new Map(); + const register = (name: string, node: ts.Node) => + locals.set(name, [...(locals.get(name) ?? []), node]); + const bindingNames = (name: ts.BindingName): string[] => + ts.isIdentifier(name) + ? [name.text] + : name.elements.flatMap((element) => + ts.isOmittedExpression(element) ? [] : bindingNames(element.name), + ); + for (const statement of file.statements) { + if (ts.isVariableStatement(statement)) { + for (const declaration of statement.declarationList.declarations) { + for (const name of bindingNames(declaration.name)) + register(name, declaration); + } + } else if (ts.isImportDeclaration(statement)) { + const clause = statement.importClause; + if (clause?.name) register(clause.name.text, clause); + if (clause?.namedBindings) { + if (ts.isNamespaceImport(clause.namedBindings)) + register(clause.namedBindings.name.text, clause); + else + for (const specifier of clause.namedBindings.elements) + register(specifier.name.text, specifier); + } + } else if ( + "name" in statement && + statement.name && + ts.isIdentifier(statement.name as ts.Node) + ) { + register((statement.name as ts.Identifier).text, statement); + } + } + + const resolveExpression = ( + expression: ts.Expression, + seen: Set, + ): "function" | "value" | "unknown" => { + if (ts.isArrowFunction(expression) || ts.isFunctionExpression(expression)) + return "function"; + if ( + ts.isParenthesizedExpression(expression) || + ts.isAsExpression(expression) || + ts.isTypeAssertionExpression(expression) || + ts.isSatisfiesExpression(expression) || + ts.isNonNullExpression(expression) + ) { + return resolveExpression(expression.expression, seen); + } + if (ts.isIdentifier(expression)) { + const kind = resolveLocal(expression.text, seen); + return kind === "type" ? "unknown" : kind; + } + if ( + ts.isCallExpression(expression) || + ts.isAwaitExpression(expression) || + ts.isPropertyAccessExpression(expression) || + ts.isElementAccessExpression(expression) || + ts.isConditionalExpression(expression) + ) + return "unknown"; + return "value"; + }; + const resolveLocal = ( + name: string, + seen = new Set(), + ): "function" | "value" | "type" | "unknown" => { + if (seen.has(name)) return "unknown"; + const declarations = locals.get(name); + if (!declarations?.length) return "unknown"; + const next = new Set([...seen, name]); + const runtime = declarations.filter( + (node) => + !ts.isInterfaceDeclaration(node) && !ts.isTypeAliasDeclaration(node), + ); + if (!runtime.length) return "type"; + const functions = runtime.filter(ts.isFunctionDeclaration); + if (functions.length === runtime.length) + return functions.filter((node) => node.body).length === 1 + ? "function" + : "unknown"; + if (runtime.length !== 1) return "unknown"; + const node = runtime[0]!; + if (ts.isImportClause(node)) return node.isTypeOnly ? "type" : "unknown"; + if (ts.isImportSpecifier(node)) + return node.isTypeOnly || node.parent.parent.isTypeOnly + ? "type" + : "unknown"; + if (hasModifier(node, ts.SyntaxKind.DeclareKeyword)) return "unknown"; + if (ts.isVariableDeclaration(node)) { + if (!ts.isIdentifier(node.name) || !node.initializer) return "unknown"; + return resolveExpression(node.initializer, next); + } + return "value"; + }; + + let commonJs = false; + const isCommonJsTarget = (node: ts.Node): boolean => { + if (ts.isIdentifier(node)) return node.text === "exports"; + if (ts.isPropertyAccessExpression(node)) + return ( + isCommonJsTarget(node.expression) || + (ts.isIdentifier(node.expression) && + node.expression.text === "module" && + node.name.text === "exports") + ); + if (ts.isElementAccessExpression(node)) + return ( + isCommonJsTarget(node.expression) || + (ts.isIdentifier(node.expression) && + node.expression.text === "module" && + ts.isStringLiteral(node.argumentExpression) && + node.argumentExpression.text === "exports") + ); + return false; + }; + const inspect = (node: ts.Node): void => { + if ( + ts.isBinaryExpression(node) && + node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && + node.operatorToken.kind <= ts.SyntaxKind.LastAssignment && + isCommonJsTarget(node.left) + ) + commonJs = true; + if (ts.isCallExpression(node) && node.arguments.some(isCommonJsTarget)) + commonJs = true; + ts.forEachChild(node, inspect); + }; + inspect(file); + if (commonJs) + return fail( + "CommonJS export mutations are not supported; use local ES module exports", + ); + + const exported: AnatomySourceExports = []; + const exportedFunctions = new Set(); + const addLocal = ( + local: string, + name: string, + ): ResultType => { + const kind = resolveLocal(local); + if (kind === "unknown") + return fail( + `Cannot determine whether export "${name}" is a local function; imported, ambient and computed exports are not supported`, + ); + if (kind !== "type") exported.push({ name, kind }); + return ok(undefined); + }; + + for (const statement of file.statements) { + if (ts.isExportDeclaration(statement)) { + if (statement.isTypeOnly) continue; + if (statement.moduleSpecifier) { + if ( + statement.exportClause && + ts.isNamedExports(statement.exportClause) && + statement.exportClause.elements.every((item) => item.isTypeOnly) + ) + continue; + return fail( + "Runtime re-exports are not supported; export a local function", + ); + } + if (!statement.exportClause || !ts.isNamedExports(statement.exportClause)) + return fail("Unsupported export declaration"); + for (const item of statement.exportClause.elements) { + if (item.isTypeOnly) continue; + const added = addLocal( + (item.propertyName ?? item.name).text, + item.name.text, + ); + if (added.isErr()) return err(added.error); + } + continue; + } + if (ts.isExportAssignment(statement)) { + if (statement.isExportEquals) + return fail("CommonJS export assignments are not supported"); + const kind = resolveExpression(statement.expression, new Set()); + if (kind === "unknown") + return fail("Cannot resolve computed default export"); + exported.push({ name: "default", kind }); + continue; + } + if (!hasModifier(statement, ts.SyntaxKind.ExportKeyword)) continue; + if ( + ts.isInterfaceDeclaration(statement) || + ts.isTypeAliasDeclaration(statement) + ) + continue; + if (hasModifier(statement, ts.SyntaxKind.DeclareKeyword)) + return fail( + "Ambient runtime exports cannot be verified in an implementation file", + ); + const isDefault = hasModifier(statement, ts.SyntaxKind.DefaultKeyword); + if (ts.isFunctionDeclaration(statement)) { + if (!statement.name) { + exported.push({ name: "default", kind: "function" }); + continue; + } + if (exportedFunctions.has(statement.name.text)) continue; + exportedFunctions.add(statement.name.text); + const added = addLocal( + statement.name.text, + isDefault ? "default" : statement.name.text, + ); + if (added.isErr()) return err(added.error); + } else if (ts.isVariableStatement(statement)) { + for (const declaration of statement.declarationList.declarations) { + for (const name of bindingNames(declaration.name)) { + const added = addLocal(name, name); + if (added.isErr()) return err(added.error); + } + } + } else if ( + ts.isClassDeclaration(statement) || + ts.isEnumDeclaration(statement) || + ts.isModuleDeclaration(statement) + ) { + exported.push({ + name: isDefault ? "default" : (statement.name?.text ?? "default"), + kind: "value", + }); + } else return fail("Unsupported runtime export declaration"); + } + return ok(exported); +}; diff --git a/packages/anatomy/src/source/index.ts b/packages/anatomy/src/source/index.ts new file mode 100644 index 0000000..35dfd35 --- /dev/null +++ b/packages/anatomy/src/source/index.ts @@ -0,0 +1 @@ +export * from "./analyzeSourceExports.js"; diff --git a/packages/anatomy/tsconfig.build.json b/packages/anatomy/tsconfig.build.json new file mode 100644 index 0000000..5b5e90e --- /dev/null +++ b/packages/anatomy/tsconfig.build.json @@ -0,0 +1,17 @@ +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "noEmit": false, + "declaration": true, + "declarationMap": false, + "rootDir": "src", + "outDir": "dist", + "paths": {} + }, + "include": [ + "src" + ], + "exclude": [ + "src/**/*.spec.ts" + ] +} diff --git a/packages/anatomy/tsconfig.json b/packages/anatomy/tsconfig.json index 63586b9..cf45886 100644 --- a/packages/anatomy/tsconfig.json +++ b/packages/anatomy/tsconfig.json @@ -11,7 +11,12 @@ "resolveJsonModule": true, "isolatedModules": true, "noEmit": true, - "types": ["node"] + "types": [ + "node" + ] }, - "include": ["src"] + "include": [ + "src" + ], + "extends": "../../tsconfig.json" } diff --git a/packages/schemas/anatomy.json b/packages/schemas/anatomy.json index a8878b3..747adb7 100644 --- a/packages/schemas/anatomy.json +++ b/packages/schemas/anatomy.json @@ -2,7 +2,7 @@ "name": "Anatomy schemas package", "purpose": "Focused copy of the repository contract for schemas; tests prevent divergence.", "structure": { - "schemaVersion": 1, + "rootMode": "contents", "defaultPolicies": { "missingRequired": "block", "unexpectedEntry": "block", @@ -141,11 +141,6 @@ "name": { "type": "literal", "value": "AnatomyPolicyValueSchema.ts" }, "quantity": "exactly_one" }, - { - "kind": "file", - "name": { "type": "literal", "value": "AnatomyPublishedVersionListInputSchema.ts" }, - "quantity": "exactly_one" - }, { "kind": "file", "name": { "type": "literal", "value": "AnatomyQuantitySchema.ts" }, @@ -178,13 +173,19 @@ }, { "kind": "file", - "name": { "type": "literal", "value": "AnatomyVersionSchema.ts" }, + "name": { "type": "literal", "value": "index.ts" }, "quantity": "exactly_one" }, { + "id": "9cd1a902-c57b-4768-9b79-20a77c246822", "kind": "file", - "name": { "type": "literal", "value": "index.ts" }, - "quantity": "exactly_one" + "name": { "type": "literal", "value": "createAnatomyNodeId.ts" }, + "quantity": "exactly_one", + "policyOverrides": {}, + "exports": { + "name": "file_stem", + "policy": "block" + } } ] }, @@ -192,6 +193,120 @@ "kind": "file", "name": { "type": "literal", "value": "index.ts" }, "quantity": "exactly_one" + }, + { + "id": "e34dac06-21bb-41ec-983f-9d2c56d1baff", + "kind": "directory", + "name": { "type": "literal", "value": "composition" }, + "quantity": "exactly_one", + "policyOverrides": {}, + "children": [ + { + "id": "c16be793-ca68-4a13-aebf-caca2a737ec6", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyBundleQueryOutcomeSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "dc5e87e5-27e8-43ec-b242-ad7587596b3f", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyBundleQueryRequestSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "b3570310-a071-47f6-a605-789f8745fcc3", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyBundleSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "478b7f75-b07c-46f9-a8bc-4c4c364b9e08", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyBundleValidationOutcomeSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "81de7097-5cc4-4bd9-b845-f3bb309e2623", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyCompositionNodeSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "20112a95-0688-4061-9d03-25c3ed304b55", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyDefinitionSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "655d4c82-4a83-4977-9cc8-4c56d95f015e", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyDiagnosticSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "2ca52c34-5deb-406f-b412-72846f67c9c0", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyFindingSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "70c660ca-9de5-476e-9ae4-74c3f734dcfb", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyMountSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "58a91a05-b06c-4ba7-9fc7-b9d0a0270146", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyOriginSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "2deacc34-b51c-439e-bc65-edd88ba74573", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyRuleSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "c836c891-fa08-4f48-875b-8c2d29b306d8", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyScanOutcomeSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "7a1e42f9-d401-41ba-a32b-965f09dca254", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyScanRequestSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "e45f2f14-03a7-41b7-acb7-1e3d3d2293ac", + "kind": "file", + "name": { "type": "literal", "value": "AnatomyTargetSchema.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "4c419753-1ea1-40ec-b11e-afd8813df35e", + "kind": "file", + "name": { "type": "literal", "value": "index.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + } + ] } ] }, @@ -199,6 +314,13 @@ "kind": "file", "name": { "type": "literal", "value": "tsconfig.json" }, "quantity": "exactly_one" + }, + { + "id": "36a6551f-1e39-4aa0-aed4-3d6f7f1d8271", + "kind": "file", + "name": { "type": "literal", "value": "tsconfig.build.json" }, + "quantity": "exactly_one", + "policyOverrides": {} } ] } diff --git a/packages/schemas/package.json b/packages/schemas/package.json index b311936..800c319 100644 --- a/packages/schemas/package.json +++ b/packages/schemas/package.json @@ -5,15 +5,30 @@ "license": "MIT", "type": "module", "exports": { - ".": "./src/index.ts", - "./anatomy": "./src/anatomy/index.ts", - "./anatomy/*": "./src/anatomy/*" + ".": { + "types": "./dist/index.d.ts", + "default": "./dist/index.js" + }, + "./anatomy": { + "types": "./dist/anatomy/index.d.ts", + "default": "./dist/anatomy/index.js" + }, + "./composition": { + "types": "./dist/composition/index.d.ts", + "default": "./dist/composition/index.js" + }, + "./anatomy/*": { + "types": "./dist/anatomy/*.d.ts", + "default": "./dist/anatomy/*.js" + } }, "scripts": { "check-types": "tsc --noEmit", "lint": "oxlint src/", "test": "vitest run --passWithNoTests", - "quality": "bun run check-types && bun run lint && bun run test" + "quality": "bun run check-types && bun run lint && bun run test", + "build": "rm -rf dist && tsc -p tsconfig.build.json", + "prepack": "bun run build" }, "dependencies": { "neverthrow": "^8.2.0", @@ -24,5 +39,15 @@ "oxlint": "^1.59.0", "typescript": "5.9.2", "vitest": "^4.1.8" + }, + "files": [ + "dist" + ], + "types": "./dist/index.d.ts", + "publishConfig": { + "access": "public" + }, + "engines": { + "node": ">=24" } } diff --git a/packages/schemas/src/anatomy/AnatomyBindingSchema.ts b/packages/schemas/src/anatomy/AnatomyBindingSchema.ts index 88452dd..515d0db 100644 --- a/packages/schemas/src/anatomy/AnatomyBindingSchema.ts +++ b/packages/schemas/src/anatomy/AnatomyBindingSchema.ts @@ -1,7 +1,7 @@ import { Result } from "neverthrow"; import { z } from "zod/v4"; -import { AnatomyBindingFormatSchema } from "./AnatomyBindingFormatSchema"; +import { AnatomyBindingFormatSchema } from "./AnatomyBindingFormatSchema.js"; const compilePattern = Result.fromThrowable( (pattern: string) => new RegExp(`^(?:${pattern})$`), diff --git a/packages/schemas/src/anatomy/AnatomyCheckWithDiagnosticsSchema.ts b/packages/schemas/src/anatomy/AnatomyCheckWithDiagnosticsSchema.ts index f4656d7..b8b1463 100644 --- a/packages/schemas/src/anatomy/AnatomyCheckWithDiagnosticsSchema.ts +++ b/packages/schemas/src/anatomy/AnatomyCheckWithDiagnosticsSchema.ts @@ -1,10 +1,9 @@ import { z } from "zod/v4"; -import { AnatomyNodeSchema } from "./AnatomyNodeSchema"; -import { AnatomyPolicyValueSchema } from "./AnatomyPolicyValueSchema"; -import { AnatomySourceExportsSchema } from "./AnatomySourceExportsSchema"; +import { AnatomyNodeSchema } from "./AnatomyNodeSchema.js"; +import { AnatomyPolicyValueSchema } from "./AnatomyPolicyValueSchema.js"; +import { AnatomySourceExportsSchema } from "./AnatomySourceExportsSchema.js"; export const AnatomyCheckWithDiagnosticsSchema = z.object({ - contractVersion: z.literal(1), operation: z.literal("check"), conforms: z.boolean(), summary: z.object({ block: z.number(), warn: z.number(), allow: z.number() }), @@ -20,7 +19,7 @@ export const AnatomyCheckWithDiagnosticsSchema = z.object({ expected: AnatomyNodeSchema.nullable(), actual: z.array(z.object({ kind: z.enum(["file", "directory"]), name: z.string() })), })), - definition: z.object({ path: z.string(), name: z.string(), schemaVersion: z.literal(1) }), + definition: z.object({ path: z.string(), name: z.string(), rootMode: z.literal("contents") }), targetPath: z.string(), ignoredNames: z.array(z.string()), fileSelection: z.enum(["filesystem", "git"]).optional(), diff --git a/packages/schemas/src/anatomy/AnatomyContract.spec.ts b/packages/schemas/src/anatomy/AnatomyContract.spec.ts index 07aacfb..e87bd0b 100644 --- a/packages/schemas/src/anatomy/AnatomyContract.spec.ts +++ b/packages/schemas/src/anatomy/AnatomyContract.spec.ts @@ -1,16 +1,16 @@ import { describe, expect, it } from "vitest"; -import { AnatomyDraftInputSchema } from "./AnatomyDraftInputSchema"; +import { AnatomyDraftInputSchema } from "./AnatomyDraftInputSchema.js"; const definition = () => ({ name: "Contract", purpose: "Reject unsupported rules", structure: { - schemaVersion: 1, + rootMode: "contents", defaultPolicies: { missingRequired: "block", unexpectedEntry: "warn", nameMismatch: "warn", nestingMismatch: "block" }, root: { children: [{ kind: "file", name: { type: "literal", value: "index.ts" }, quantity: "exactly_one" }] }, }, }); -describe("Anatomy definition compatibility", () => { +describe("Anatomy definition contract", () => { it("allows an explicit function export rule only on files", () => { const input = definition(); Object.assign(input.structure.root.children[0]!, { exports: { name: "file_stem" } }); @@ -25,14 +25,14 @@ describe("Anatomy definition compatibility", () => { Object.assign(input.structure.root.children[0]!, { exports: { name: "file_stem", allowDefault: true } }); expect(AnatomyDraftInputSchema.safeParse(input).success).toBe(false); }); - it("accepts version one with omitted IDs and overrides", () => { + it("accepts the current format with omitted IDs and overrides", () => { expect(AnatomyDraftInputSchema.safeParse(definition()).success).toBe(true); }); - it("rejects unsupported versions and node kinds", () => { + it("rejects unknown root modes and node kinds", () => { const input = definition(); - input.structure.schemaVersion = 2; + input.structure.rootMode = "unknown"; expect(AnatomyDraftInputSchema.safeParse(input).success).toBe(false); - input.structure.schemaVersion = 1; + input.structure.rootMode = "contents"; input.structure.root.children[0]!.kind = "dependency"; expect(AnatomyDraftInputSchema.safeParse(input).success).toBe(false); }); diff --git a/packages/schemas/src/anatomy/AnatomyDetailSchema.ts b/packages/schemas/src/anatomy/AnatomyDetailSchema.ts index c7b3a93..0440f2b 100644 --- a/packages/schemas/src/anatomy/AnatomyDetailSchema.ts +++ b/packages/schemas/src/anatomy/AnatomyDetailSchema.ts @@ -1,9 +1,8 @@ import { z } from "zod/v4"; -import { AnatomyDraftSchema } from "./AnatomyDraftSchema"; -import { AnatomyVersionSchema } from "./AnatomyVersionSchema"; +import { AnatomyDraftSchema } from "./AnatomyDraftSchema.js"; -/** Complete Anatomy aggregate view, including its draft, version history, and usage. */ +/** Complete Anatomy aggregate view, including its current draft and usage. */ export const AnatomyDetailSchema = z.object({ /** Unique Anatomy identifier. */ id: z.string(), @@ -12,8 +11,6 @@ export const AnatomyDetailSchema = z.object({ archivedAt: z.date().nullable(), /** Current editable draft, or null when no draft exists. */ draft: AnatomyDraftSchema.nullable(), - /** Immutable versions ordered by publication time. */ - versions: z.array(AnatomyVersionSchema), /** Number of current Crate references. */ usageCount: z.number().int().nonnegative(), diff --git a/packages/schemas/src/anatomy/AnatomyDirectoryEntrySchema.ts b/packages/schemas/src/anatomy/AnatomyDirectoryEntrySchema.ts index f52189a..3b43195 100644 --- a/packages/schemas/src/anatomy/AnatomyDirectoryEntrySchema.ts +++ b/packages/schemas/src/anatomy/AnatomyDirectoryEntrySchema.ts @@ -1,7 +1,7 @@ import { z } from "zod/v4"; -import { AnatomyFileEntrySchema, type AnatomyFileEntry } from "./AnatomyFileEntrySchema"; -import { AnatomyNodeSchema, type AnatomyNode } from "./AnatomyNodeSchema"; +import { AnatomyFileEntrySchema, type AnatomyFileEntry } from "./AnatomyFileEntrySchema.js"; +import { AnatomyNodeSchema, type AnatomyNode } from "./AnatomyNodeSchema.js"; /** Directory node and its recursive children in an Anatomy tree. */ export const AnatomyDirectoryEntrySchema: z.ZodType< diff --git a/packages/schemas/src/anatomy/AnatomyDraftCreateInputSchema.ts b/packages/schemas/src/anatomy/AnatomyDraftCreateInputSchema.ts index d63fc8d..2281a33 100644 --- a/packages/schemas/src/anatomy/AnatomyDraftCreateInputSchema.ts +++ b/packages/schemas/src/anatomy/AnatomyDraftCreateInputSchema.ts @@ -1,5 +1,5 @@ import { z } from "zod/v4"; -import { AnatomyDraftInputSchema } from "./AnatomyDraftInputSchema"; +import { AnatomyDraftInputSchema } from "./AnatomyDraftInputSchema.js"; export const AnatomyDraftCreateInputSchema = AnatomyDraftInputSchema.extend({ id: z.string().uuid().optional(), diff --git a/packages/schemas/src/anatomy/AnatomyDraftInput.spec.ts b/packages/schemas/src/anatomy/AnatomyDraftInput.spec.ts index 260840e..6fe9e09 100644 --- a/packages/schemas/src/anatomy/AnatomyDraftInput.spec.ts +++ b/packages/schemas/src/anatomy/AnatomyDraftInput.spec.ts @@ -1,5 +1,5 @@ import { describe, expect, it } from "vitest"; -import { AnatomyDraftInputSchema } from "./AnatomyDraftInputSchema"; +import { AnatomyDraftInputSchema } from "./AnatomyDraftInputSchema.js"; const defaultPolicies = { missingRequired: "block" as const, @@ -14,7 +14,7 @@ describe("AnatomyDraftInputSchema", () => { name: "Example", purpose: "Show the smallest useful Anatomy JSON shape.", structure: { - schemaVersion: 1, + rootMode: "contents", defaultPolicies, root: { children: [ @@ -63,7 +63,7 @@ describe("AnatomyDraftInputSchema", () => { name: "Bound example", purpose: "Constrain a captured name.", structure: { - schemaVersion: 1, + rootMode: "contents", defaultPolicies, bindings: { Name: { format: "PascalCase", pattern: "[A-Z][A-Za-z0-9]*" }, @@ -80,7 +80,7 @@ describe("AnatomyDraftInputSchema", () => { name: "Invalid", purpose: "", structure: { - schemaVersion: 1, + rootMode: "contents", defaultPolicies, bindings: { Name: { pattern: "[" } }, root: { children: [] }, @@ -92,7 +92,7 @@ describe("AnatomyDraftInputSchema", () => { name: "Invalid binding name", purpose: "", structure: { - schemaVersion: 1, + rootMode: "contents", defaultPolicies, bindings: { "not a name": { format: "PascalCase" } }, root: { children: [] }, diff --git a/packages/schemas/src/anatomy/AnatomyDraftInputSchema.ts b/packages/schemas/src/anatomy/AnatomyDraftInputSchema.ts index f826447..a42a53c 100644 --- a/packages/schemas/src/anatomy/AnatomyDraftInputSchema.ts +++ b/packages/schemas/src/anatomy/AnatomyDraftInputSchema.ts @@ -1,6 +1,6 @@ import { z } from "zod/v4"; -import { AnatomyStructureSchema } from "./AnatomyStructureSchema"; +import { AnatomyStructureSchema } from "./AnatomyStructureSchema.js"; /** Author-managed definition used to create or replace an Anatomy draft. */ export const AnatomyDraftInputSchema = z.strictObject({ diff --git a/packages/schemas/src/anatomy/AnatomyDraftSaveInputSchema.ts b/packages/schemas/src/anatomy/AnatomyDraftSaveInputSchema.ts index 36ade5a..dda0d9e 100644 --- a/packages/schemas/src/anatomy/AnatomyDraftSaveInputSchema.ts +++ b/packages/schemas/src/anatomy/AnatomyDraftSaveInputSchema.ts @@ -1,6 +1,6 @@ import { z } from "zod/v4"; -import { AnatomyDraftInputSchema } from "./AnatomyDraftInputSchema"; +import { AnatomyDraftInputSchema } from "./AnatomyDraftInputSchema.js"; /** Input contract for saving an Anatomy draft. */ export const AnatomyDraftSaveInputSchema = AnatomyDraftInputSchema.extend({ diff --git a/packages/schemas/src/anatomy/AnatomyDraftSchema.ts b/packages/schemas/src/anatomy/AnatomyDraftSchema.ts index b9d8e05..9799baf 100644 --- a/packages/schemas/src/anatomy/AnatomyDraftSchema.ts +++ b/packages/schemas/src/anatomy/AnatomyDraftSchema.ts @@ -1,6 +1,6 @@ import { z } from "zod/v4"; -import { AnatomyDraftInputSchema } from "./AnatomyDraftInputSchema"; +import { AnatomyDraftInputSchema } from "./AnatomyDraftInputSchema.js"; /** Editable working draft of an Anatomy before publication. */ export const AnatomyDraftSchema = AnatomyDraftInputSchema.extend({ @@ -9,8 +9,6 @@ export const AnatomyDraftSchema = AnatomyDraftInputSchema.extend({ /** Identifier of the Anatomy that owns the draft. */ anatomyId: z.string(), - /** Historical version the draft is based on, or null when created from scratch. */ - basedOnVersionId: z.string().nullable(), /** Draft revision used for optimistic concurrency control. */ revision: z.number().int().positive(), diff --git a/packages/schemas/src/anatomy/AnatomyEntrySchema.ts b/packages/schemas/src/anatomy/AnatomyEntrySchema.ts index 0300cb8..25d0d1b 100644 --- a/packages/schemas/src/anatomy/AnatomyEntrySchema.ts +++ b/packages/schemas/src/anatomy/AnatomyEntrySchema.ts @@ -3,8 +3,8 @@ import { z } from "zod/v4"; import { AnatomyDirectoryEntrySchema, type AnatomyDirectoryEntry, -} from "./AnatomyDirectoryEntrySchema"; -import { AnatomyFileEntrySchema, type AnatomyFileEntry } from "./AnatomyFileEntrySchema"; +} from "./AnatomyDirectoryEntrySchema.js"; +import { AnatomyFileEntrySchema, type AnatomyFileEntry } from "./AnatomyFileEntrySchema.js"; type AnatomyEntryValue = AnatomyFileEntry | AnatomyDirectoryEntry; diff --git a/packages/schemas/src/anatomy/AnatomyFileEntrySchema.ts b/packages/schemas/src/anatomy/AnatomyFileEntrySchema.ts index 77829a1..07bf2db 100644 --- a/packages/schemas/src/anatomy/AnatomyFileEntrySchema.ts +++ b/packages/schemas/src/anatomy/AnatomyFileEntrySchema.ts @@ -1,14 +1,15 @@ +import { createAnatomyNodeId } from "./createAnatomyNodeId.js"; import { z } from "zod/v4"; -import { AnatomyNameExpressionSchema } from "./AnatomyNameExpressionSchema"; -import { AnatomyPolicyOverridesSchema } from "./AnatomyPolicyOverridesSchema"; -import { AnatomyQuantitySchema } from "./AnatomyQuantitySchema"; -import { AnatomyFunctionExportRuleSchema } from "./AnatomyFunctionExportRuleSchema"; +import { AnatomyNameExpressionSchema } from "./AnatomyNameExpressionSchema.js"; +import { AnatomyPolicyOverridesSchema } from "./AnatomyPolicyOverridesSchema.js"; +import { AnatomyQuantitySchema } from "./AnatomyQuantitySchema.js"; +import { AnatomyFunctionExportRuleSchema } from "./AnatomyFunctionExportRuleSchema.js"; /** File requirement with naming, quantity, and policy constraints. */ export const AnatomyFileEntrySchema = z.strictObject({ /** Unique file-entry identifier, generated during schema parsing when omitted. */ - id: z.string().uuid().default(() => crypto.randomUUID()), + id: z.string().uuid().default(createAnatomyNodeId), /** Literal filename or placeholder expression. */ name: AnatomyNameExpressionSchema, /** Allowed number of occurrences for the file. */ diff --git a/packages/schemas/src/anatomy/AnatomyFunctionExportCheckSchema.ts b/packages/schemas/src/anatomy/AnatomyFunctionExportCheckSchema.ts index ee0ac3e..691a886 100644 --- a/packages/schemas/src/anatomy/AnatomyFunctionExportCheckSchema.ts +++ b/packages/schemas/src/anatomy/AnatomyFunctionExportCheckSchema.ts @@ -1,5 +1,5 @@ import { z } from "zod/v4"; -import { AnatomyPolicyValueSchema } from "./AnatomyPolicyValueSchema"; +import { AnatomyPolicyValueSchema } from "./AnatomyPolicyValueSchema.js"; export const AnatomyFunctionExportCheckSchema = z.strictObject({ path: z.string(), diff --git a/packages/schemas/src/anatomy/AnatomyFunctionExportRuleSchema.ts b/packages/schemas/src/anatomy/AnatomyFunctionExportRuleSchema.ts index 09cf84e..f28f500 100644 --- a/packages/schemas/src/anatomy/AnatomyFunctionExportRuleSchema.ts +++ b/packages/schemas/src/anatomy/AnatomyFunctionExportRuleSchema.ts @@ -1,6 +1,6 @@ import { z } from "zod/v4"; -import { AnatomyNameExpressionSchema } from "./AnatomyNameExpressionSchema"; -import { AnatomyPolicyValueSchema } from "./AnatomyPolicyValueSchema"; +import { AnatomyNameExpressionSchema } from "./AnatomyNameExpressionSchema.js"; +import { AnatomyPolicyValueSchema } from "./AnatomyPolicyValueSchema.js"; export const AnatomyFunctionExportRuleSchema = z.strictObject({ name: z.union([z.literal("file_stem"), AnatomyNameExpressionSchema]), diff --git a/packages/schemas/src/anatomy/AnatomyListInputSchema.ts b/packages/schemas/src/anatomy/AnatomyListInputSchema.ts index 9b92d59..2eb9ef4 100644 --- a/packages/schemas/src/anatomy/AnatomyListInputSchema.ts +++ b/packages/schemas/src/anatomy/AnatomyListInputSchema.ts @@ -1,6 +1,6 @@ import { z } from "zod/v4"; -import { AnatomyStatusSchema } from "./AnatomyStatusSchema"; +import { AnatomyStatusSchema } from "./AnatomyStatusSchema.js"; /** Input contract for paginated Anatomy list queries. */ export const AnatomyListInputSchema = z.object({ diff --git a/packages/schemas/src/anatomy/AnatomyNodeSchema.ts b/packages/schemas/src/anatomy/AnatomyNodeSchema.ts index 706904a..9770250 100644 --- a/packages/schemas/src/anatomy/AnatomyNodeSchema.ts +++ b/packages/schemas/src/anatomy/AnatomyNodeSchema.ts @@ -1,7 +1,7 @@ import { z } from "zod/v4"; -import { AnatomyEntrySchema, type AnatomyEntry } from "./AnatomyEntrySchema"; -import { AnatomyOneOfGroupSchema, type AnatomyOneOfGroup } from "./AnatomyOneOfGroupSchema"; +import { AnatomyEntrySchema, type AnatomyEntry } from "./AnatomyEntrySchema.js"; +import { AnatomyOneOfGroupSchema, type AnatomyOneOfGroup } from "./AnatomyOneOfGroupSchema.js"; /** Any node permitted in an Anatomy tree, including entries and one-of groups. */ export const AnatomyNodeSchema: z.ZodType = z.lazy(() => diff --git a/packages/schemas/src/anatomy/AnatomyOneOfGroupSchema.ts b/packages/schemas/src/anatomy/AnatomyOneOfGroupSchema.ts index 2c0f8d8..cde0a45 100644 --- a/packages/schemas/src/anatomy/AnatomyOneOfGroupSchema.ts +++ b/packages/schemas/src/anatomy/AnatomyOneOfGroupSchema.ts @@ -1,6 +1,7 @@ +import { createAnatomyNodeId } from "./createAnatomyNodeId.js"; import { z } from "zod/v4"; -import { AnatomyEntrySchema, type AnatomyEntry } from "./AnatomyEntrySchema"; +import { AnatomyEntrySchema, type AnatomyEntry } from "./AnatomyEntrySchema.js"; /** One-of group requiring a match count across multiple candidate entries. */ export const AnatomyOneOfGroupSchema: z.ZodType<{ @@ -11,7 +12,7 @@ export const AnatomyOneOfGroupSchema: z.ZodType<{ alternatives: AnatomyEntry[]; }> = z.strictObject({ /** Unique group identifier, generated during schema parsing when omitted. */ - id: z.string().uuid().default(() => crypto.randomUUID()), + id: z.string().uuid().default(createAnatomyNodeId), /** Node discriminant, fixed to one_of. */ kind: z.literal("one_of"), /** Minimum number of alternatives that must match. */ diff --git a/packages/schemas/src/anatomy/AnatomyPoliciesSchema.ts b/packages/schemas/src/anatomy/AnatomyPoliciesSchema.ts index 91049d3..1d9397c 100644 --- a/packages/schemas/src/anatomy/AnatomyPoliciesSchema.ts +++ b/packages/schemas/src/anatomy/AnatomyPoliciesSchema.ts @@ -1,5 +1,5 @@ import { z } from "zod/v4"; -import { AnatomyPolicyValueSchema } from "./AnatomyPolicyValueSchema"; +import { AnatomyPolicyValueSchema } from "./AnatomyPolicyValueSchema.js"; /** Default policies applied when a Crate does not conform to an Anatomy. */ export const AnatomyPoliciesSchema = z.strictObject({ diff --git a/packages/schemas/src/anatomy/AnatomyPublishedVersionListInputSchema.ts b/packages/schemas/src/anatomy/AnatomyPublishedVersionListInputSchema.ts deleted file mode 100644 index a99ab57..0000000 --- a/packages/schemas/src/anatomy/AnatomyPublishedVersionListInputSchema.ts +++ /dev/null @@ -1,17 +0,0 @@ -import { z } from "zod/v4"; - -/** Input contract for querying a list of published Anatomy versions. */ -export const AnatomyPublishedVersionListInputSchema = z.object({ - /** Search term used for fuzzy matching against version names or purposes. */ - search: z.string().trim().optional(), - /** Identifier of the owning Anatomy. */ - anatomyId: z.string().optional(), - /** One-based page number. */ - page: z.number().int().positive().optional(), - /** Maximum number of versions returned per page. */ - pageSize: z.number().int().positive().max(100).optional(), -}); - -export type AnatomyPublishedVersionListInput = z.infer< - typeof AnatomyPublishedVersionListInputSchema ->; diff --git a/packages/schemas/src/anatomy/AnatomyQueryWithConstraintsSchema.ts b/packages/schemas/src/anatomy/AnatomyQueryWithConstraintsSchema.ts index adb7aaf..f51ca15 100644 --- a/packages/schemas/src/anatomy/AnatomyQueryWithConstraintsSchema.ts +++ b/packages/schemas/src/anatomy/AnatomyQueryWithConstraintsSchema.ts @@ -1,11 +1,10 @@ import { z } from "zod/v4"; -import { AnatomyNodeSchema } from "./AnatomyNodeSchema"; -import { AnatomyPoliciesSchema } from "./AnatomyPoliciesSchema"; -import { AnatomyBindingSchema } from "./AnatomyBindingSchema"; -import { AnatomyQuantitySchema } from "./AnatomyQuantitySchema"; +import { AnatomyNodeSchema } from "./AnatomyNodeSchema.js"; +import { AnatomyPoliciesSchema } from "./AnatomyPoliciesSchema.js"; +import { AnatomyBindingSchema } from "./AnatomyBindingSchema.js"; +import { AnatomyQuantitySchema } from "./AnatomyQuantitySchema.js"; export const AnatomyQueryWithConstraintsSchema = z.object({ - contractVersion: z.literal(1), operation: z.literal("query"), path: z.string(), scopePath: z.string(), diff --git a/packages/schemas/src/anatomy/AnatomyStructureSchema.ts b/packages/schemas/src/anatomy/AnatomyStructureSchema.ts index 14bfafb..3bd43b1 100644 --- a/packages/schemas/src/anatomy/AnatomyStructureSchema.ts +++ b/packages/schemas/src/anatomy/AnatomyStructureSchema.ts @@ -1,13 +1,13 @@ import { z } from "zod/v4"; -import { AnatomyPoliciesSchema } from "./AnatomyPoliciesSchema"; -import { AnatomyNodeSchema } from "./AnatomyNodeSchema"; -import { AnatomyBindingSchema } from "./AnatomyBindingSchema"; +import { AnatomyPoliciesSchema } from "./AnatomyPoliciesSchema.js"; +import { AnatomyNodeSchema } from "./AnatomyNodeSchema.js"; +import { AnatomyBindingSchema } from "./AnatomyBindingSchema.js"; /** Recursive filesystem structure contract that an Anatomy must satisfy. */ export const AnatomyStructureSchema = z.strictObject({ - /** Structure document format version used for future-compatible migrations. */ - schemaVersion: z.literal(1), + /** Root mode for normalized matcher input. */ + rootMode: z.literal("contents"), /** Default policies used by nodes that do not provide local overrides. */ defaultPolicies: AnatomyPoliciesSchema, /** Named placeholder constraints shared by matching descendants. */ diff --git a/packages/schemas/src/anatomy/AnatomySummarySchema.ts b/packages/schemas/src/anatomy/AnatomySummarySchema.ts index 2298c36..0fb3589 100644 --- a/packages/schemas/src/anatomy/AnatomySummarySchema.ts +++ b/packages/schemas/src/anatomy/AnatomySummarySchema.ts @@ -16,8 +16,6 @@ export const AnatomySummarySchema = z.object({ updatedAt: z.date(), /** Whether an editable draft exists. */ hasDraft: z.boolean(), - /** Latest published version number, or null when never published. */ - latestVersion: z.number().int().positive().nullable(), /** Number of current Crate references. */ usageCount: z.number().int().nonnegative(), }); diff --git a/packages/schemas/src/anatomy/AnatomyVersionSchema.ts b/packages/schemas/src/anatomy/AnatomyVersionSchema.ts deleted file mode 100644 index dfaa971..0000000 --- a/packages/schemas/src/anatomy/AnatomyVersionSchema.ts +++ /dev/null @@ -1,19 +0,0 @@ -import { z } from "zod/v4"; - -import { AnatomyDraftInputSchema } from "./AnatomyDraftInputSchema"; - -/** Immutable historical snapshot of a published Anatomy definition. */ -export const AnatomyVersionSchema = AnatomyDraftInputSchema.extend({ - /** Unique version record identifier. */ - id: z.string(), - /** Identifier of the Anatomy that owns the version. */ - anatomyId: z.string(), - /** Version number that increments within one Anatomy. */ - version: z.number().int().positive(), - /** Publication timestamp for the version. */ - publishedAt: z.date(), - /** Number of Crates currently referencing this version. */ - usageCount: z.number().int().nonnegative(), -}); - -export type AnatomyVersion = z.infer; diff --git a/packages/schemas/src/anatomy/createAnatomyNodeId.ts b/packages/schemas/src/anatomy/createAnatomyNodeId.ts new file mode 100644 index 0000000..7b4282c --- /dev/null +++ b/packages/schemas/src/anatomy/createAnatomyNodeId.ts @@ -0,0 +1 @@ +export const createAnatomyNodeId = (): string => crypto.randomUUID(); diff --git a/packages/schemas/src/anatomy/index.ts b/packages/schemas/src/anatomy/index.ts index 8f17d53..f58a7d1 100644 --- a/packages/schemas/src/anatomy/index.ts +++ b/packages/schemas/src/anatomy/index.ts @@ -1,28 +1,27 @@ -export * from "./AnatomyDetailSchema"; -export * from "./AnatomyBindingSchema"; -export * from "./AnatomyBindingFormatSchema"; -export * from "./AnatomyDirectoryEntrySchema"; -export * from "./AnatomyDraftSchema"; -export * from "./AnatomyDraftCreateInputSchema"; -export * from "./AnatomyDraftInputSchema"; -export * from "./AnatomyDraftSaveInputSchema"; -export * from "./AnatomyFileEntrySchema"; -export * from "./AnatomyEntrySchema"; -export * from "./AnatomyListInputSchema"; -export * from "./AnatomyNameExpressionSchema"; -export * from "./AnatomyNodeSchema"; -export * from "./AnatomyOneOfGroupSchema"; -export * from "./AnatomyPolicyOverridesSchema"; -export * from "./AnatomyPublishedVersionListInputSchema"; -export * from "./AnatomyPoliciesSchema"; -export * from "./AnatomyPolicyValueSchema"; -export * from "./AnatomyQuantitySchema"; -export * from "./AnatomyStatusSchema"; -export * from "./AnatomyStructureSchema"; -export * from "./AnatomySummarySchema"; -export * from "./AnatomyVersionSchema"; -export * from "./AnatomyQueryWithConstraintsSchema"; -export * from "./AnatomyCheckWithDiagnosticsSchema"; -export * from "./AnatomyFunctionExportRuleSchema"; -export * from "./AnatomySourceExportsSchema"; -export * from "./AnatomyFunctionExportCheckSchema"; +export * from "./AnatomyDetailSchema.js"; +export * from "./AnatomyBindingSchema.js"; +export * from "./AnatomyBindingFormatSchema.js"; +export * from "./AnatomyDirectoryEntrySchema.js"; +export * from "./AnatomyDraftSchema.js"; +export * from "./AnatomyDraftCreateInputSchema.js"; +export * from "./AnatomyDraftInputSchema.js"; +export * from "./AnatomyDraftSaveInputSchema.js"; +export * from "./AnatomyFileEntrySchema.js"; +export * from "./AnatomyEntrySchema.js"; +export * from "./AnatomyListInputSchema.js"; +export * from "./AnatomyNameExpressionSchema.js"; +export * from "./AnatomyNodeSchema.js"; +export * from "./AnatomyOneOfGroupSchema.js"; +export * from "./AnatomyPolicyOverridesSchema.js"; +export * from "./AnatomyPoliciesSchema.js"; +export * from "./AnatomyPolicyValueSchema.js"; +export * from "./AnatomyQuantitySchema.js"; +export * from "./AnatomyStatusSchema.js"; +export * from "./AnatomyStructureSchema.js"; +export * from "./AnatomySummarySchema.js"; +export * from "./AnatomyQueryWithConstraintsSchema.js"; +export * from "./AnatomyCheckWithDiagnosticsSchema.js"; +export * from "./AnatomyFunctionExportRuleSchema.js"; +export * from "./AnatomySourceExportsSchema.js"; +export * from "./AnatomyFunctionExportCheckSchema.js"; +export * from "./createAnatomyNodeId.js"; diff --git a/packages/schemas/src/composition/AnatomyBundleQueryOutcomeSchema.ts b/packages/schemas/src/composition/AnatomyBundleQueryOutcomeSchema.ts new file mode 100644 index 0000000..f814f76 --- /dev/null +++ b/packages/schemas/src/composition/AnatomyBundleQueryOutcomeSchema.ts @@ -0,0 +1,32 @@ +import { z } from "zod/v4"; +import { AnatomyDiagnosticSchema } from "./AnatomyDiagnosticSchema.js"; +import { AnatomyOriginSchema } from "./AnatomyOriginSchema.js"; +import { AnatomyMountSchema } from "./AnatomyMountSchema.js"; +import { AnatomyPoliciesSchema } from "../anatomy/AnatomyPoliciesSchema.js"; +import { AnatomyRuleSchema } from "./AnatomyRuleSchema.js"; +export const AnatomyBundleQueryOutcomeSchema = z.discriminatedUnion("status", [ + z.strictObject({ + operation: z.literal("query"), + status: z.enum(["resolved", "unmatched", "ambiguous", "mismatch"]), + path: z.string(), + scopePath: z.string(), + reason: z.string().nullable(), + captures: z.record(z.string(), z.string()), + mounts: z.array(AnatomyMountSchema), + rules: z.array( + z.strictObject({ + origin: AnatomyOriginSchema, + node: AnatomyRuleSchema.optional(), + policies: AnatomyPoliciesSchema, + }), + ), + }), + z.strictObject({ + operation: z.literal("query"), + status: z.literal("error"), + diagnostics: z.array(AnatomyDiagnosticSchema), + }), +]); +export type AnatomyBundleQueryOutcome = z.infer< + typeof AnatomyBundleQueryOutcomeSchema +>; diff --git a/packages/schemas/src/composition/AnatomyBundleQueryRequestSchema.ts b/packages/schemas/src/composition/AnatomyBundleQueryRequestSchema.ts new file mode 100644 index 0000000..a5999d5 --- /dev/null +++ b/packages/schemas/src/composition/AnatomyBundleQueryRequestSchema.ts @@ -0,0 +1,10 @@ +import { z } from "zod/v4"; + +export const AnatomyBundleQueryRequestSchema = z.strictObject({ + bundle: z.unknown(), + path: z.string(), + targetName: z.string().optional(), +}); +export type AnatomyBundleQueryRequest = z.infer< + typeof AnatomyBundleQueryRequestSchema +>; diff --git a/packages/schemas/src/composition/AnatomyBundleSchema.ts b/packages/schemas/src/composition/AnatomyBundleSchema.ts new file mode 100644 index 0000000..b8f2a45 --- /dev/null +++ b/packages/schemas/src/composition/AnatomyBundleSchema.ts @@ -0,0 +1,14 @@ +import { z } from "zod/v4"; +import { AnatomyDefinitionSchema } from "./AnatomyDefinitionSchema.js"; +export const AnatomyBundleSchema = z.strictObject({ + root: z.string().regex(/^[a-z][a-z0-9-]*$/), + definitions: z + .array( + z.strictObject({ + key: z.string().regex(/^[a-z][a-z0-9-]*$/), + definition: AnatomyDefinitionSchema, + }), + ) + .min(1), +}); +export type AnatomyBundle = z.infer; diff --git a/packages/schemas/src/composition/AnatomyBundleValidationOutcomeSchema.ts b/packages/schemas/src/composition/AnatomyBundleValidationOutcomeSchema.ts new file mode 100644 index 0000000..8b8fc2e --- /dev/null +++ b/packages/schemas/src/composition/AnatomyBundleValidationOutcomeSchema.ts @@ -0,0 +1,16 @@ +import { z } from "zod/v4"; +import { AnatomyBundleSchema } from "./AnatomyBundleSchema.js"; +import { AnatomyDiagnosticSchema } from "./AnatomyDiagnosticSchema.js"; +export const AnatomyBundleValidationOutcomeSchema = z.discriminatedUnion( + "status", + [ + z.strictObject({ status: z.literal("valid"), bundle: AnatomyBundleSchema }), + z.strictObject({ + status: z.literal("error"), + diagnostics: z.array(AnatomyDiagnosticSchema), + }), + ], +); +export type AnatomyBundleValidationOutcome = z.infer< + typeof AnatomyBundleValidationOutcomeSchema +>; diff --git a/packages/schemas/src/composition/AnatomyCompositionNodeSchema.ts b/packages/schemas/src/composition/AnatomyCompositionNodeSchema.ts new file mode 100644 index 0000000..adcb25a --- /dev/null +++ b/packages/schemas/src/composition/AnatomyCompositionNodeSchema.ts @@ -0,0 +1,14 @@ +import { z } from "zod/v4"; +import { AnatomyFileEntrySchema } from "../anatomy/AnatomyFileEntrySchema.js"; +export const AnatomyCompositionNodeSchema = AnatomyFileEntrySchema.omit({ + kind: true, + exports: true, + name: true, +}).extend({ + kind: z.literal("composition"), + ref: z.string().regex(/^[a-z][a-z0-9-]*$/), + name: AnatomyFileEntrySchema.shape.name.optional(), +}); +export type AnatomyCompositionNode = z.infer< + typeof AnatomyCompositionNodeSchema +>; diff --git a/packages/schemas/src/composition/AnatomyDefinitionSchema.ts b/packages/schemas/src/composition/AnatomyDefinitionSchema.ts new file mode 100644 index 0000000..ba0ecb6 --- /dev/null +++ b/packages/schemas/src/composition/AnatomyDefinitionSchema.ts @@ -0,0 +1,29 @@ +import { z } from "zod/v4"; +import { AnatomyDraftInputSchema } from "../anatomy/AnatomyDraftInputSchema.js"; +import { AnatomyStructureSchema } from "../anatomy/AnatomyStructureSchema.js"; +import { AnatomyFileEntrySchema } from "../anatomy/AnatomyFileEntrySchema.js"; +import { AnatomyRuleSchema } from "./AnatomyRuleSchema.js"; +const base = AnatomyStructureSchema.omit({ rootMode: true, root: true }); +const directory = AnatomyFileEntrySchema.omit({ + kind: true, + exports: true, +}).extend({ + kind: z.literal("directory"), + quantity: z.literal("exactly_one"), + children: z.array(AnatomyRuleSchema), +}); +export const AnatomyDefinitionSchema = AnatomyDraftInputSchema.omit({ + structure: true, +}).extend({ + structure: z.discriminatedUnion("rootMode", [ + base.extend({ + rootMode: z.literal("contents"), + root: z.strictObject({ children: z.array(AnatomyRuleSchema) }), + }), + base.extend({ + rootMode: z.literal("entry"), + root: directory, + }), + ]), +}); +export type AnatomyDefinition = z.infer; diff --git a/packages/schemas/src/composition/AnatomyDiagnosticSchema.ts b/packages/schemas/src/composition/AnatomyDiagnosticSchema.ts new file mode 100644 index 0000000..752891c --- /dev/null +++ b/packages/schemas/src/composition/AnatomyDiagnosticSchema.ts @@ -0,0 +1,23 @@ +import { z } from "zod/v4"; +import { AnatomyOriginSchema } from "./AnatomyOriginSchema.js"; +export const AnatomyDiagnosticSchema = z.strictObject({ + code: z.enum([ + "invalid_bundle", + "duplicate_definition_key", + "missing_root", + "unavailable_reference", + "composition_cycle", + "invalid_mount", + "ambiguous_mount", + "invalid_tree", + "incomplete_tree", + "source_unavailable", + "source_analysis_error", + "resource_limit_exceeded", + ]), + message: z.string(), + entryPath: z.string().optional(), + origin: AnatomyOriginSchema.optional(), + chain: z.array(AnatomyOriginSchema).optional(), +}); +export type AnatomyDiagnostic = z.infer; diff --git a/packages/schemas/src/composition/AnatomyFindingSchema.ts b/packages/schemas/src/composition/AnatomyFindingSchema.ts new file mode 100644 index 0000000..684e5a0 --- /dev/null +++ b/packages/schemas/src/composition/AnatomyFindingSchema.ts @@ -0,0 +1,21 @@ +import { z } from "zod/v4"; +import { AnatomyOriginSchema } from "./AnatomyOriginSchema.js"; +import { AnatomyMountSchema } from "./AnatomyMountSchema.js"; +import { AnatomyPolicyValueSchema } from "../anatomy/AnatomyPolicyValueSchema.js"; +export const AnatomyFindingSchema = z.strictObject({ + code: z.string(), + severity: AnatomyPolicyValueSchema, + message: z.string(), + entryPath: z.string(), + scopePath: z.string(), + origin: AnatomyOriginSchema, + mounts: z.array(AnatomyMountSchema), + captures: z.record(z.string(), z.string()), + policyOrigin: z.strictObject({ + origin: AnatomyOriginSchema, + policy: z.string(), + }), + instanceKey: z.string(), + issueKey: z.string(), +}); +export type AnatomyFinding = z.infer; diff --git a/packages/schemas/src/composition/AnatomyMountSchema.ts b/packages/schemas/src/composition/AnatomyMountSchema.ts new file mode 100644 index 0000000..6774f85 --- /dev/null +++ b/packages/schemas/src/composition/AnatomyMountSchema.ts @@ -0,0 +1,9 @@ +import { z } from "zod/v4"; +import { AnatomyOriginSchema } from "./AnatomyOriginSchema.js"; +export const AnatomyMountSchema = z.strictObject({ + owner: AnatomyOriginSchema, + ref: z.string(), + mountPath: z.string(), + captures: z.record(z.string(), z.string()), +}); +export type AnatomyMount = z.infer; diff --git a/packages/schemas/src/composition/AnatomyOriginSchema.ts b/packages/schemas/src/composition/AnatomyOriginSchema.ts new file mode 100644 index 0000000..16762e1 --- /dev/null +++ b/packages/schemas/src/composition/AnatomyOriginSchema.ts @@ -0,0 +1,8 @@ +import { z } from "zod/v4"; + +export const AnatomyOriginSchema = z.strictObject({ + definitionKey: z.string(), + rulePath: z.string(), + sourceNodeId: z.string().nullable(), +}); +export type AnatomyOrigin = z.infer; diff --git a/packages/schemas/src/composition/AnatomyRuleSchema.ts b/packages/schemas/src/composition/AnatomyRuleSchema.ts new file mode 100644 index 0000000..aea7de9 --- /dev/null +++ b/packages/schemas/src/composition/AnatomyRuleSchema.ts @@ -0,0 +1,20 @@ +import { z } from "zod/v4"; +import { AnatomyFileEntrySchema } from "../anatomy/AnatomyFileEntrySchema.js"; +import { AnatomyOneOfGroupSchema } from "../anatomy/AnatomyOneOfGroupSchema.js"; +import { AnatomyCompositionNodeSchema } from "./AnatomyCompositionNodeSchema.js"; +const directory = AnatomyFileEntrySchema.omit({ + kind: true, + exports: true, +}).extend({ + kind: z.literal("directory"), + get children(): z.ZodArray { + return z.array(AnatomyRuleSchema); + }, +}); +export const AnatomyRuleSchema = z.union([ + AnatomyFileEntrySchema, + directory, + AnatomyOneOfGroupSchema, + AnatomyCompositionNodeSchema, +]); +export type AnatomyRule = z.infer; diff --git a/packages/schemas/src/composition/AnatomyScanOutcomeSchema.ts b/packages/schemas/src/composition/AnatomyScanOutcomeSchema.ts new file mode 100644 index 0000000..ea0696b --- /dev/null +++ b/packages/schemas/src/composition/AnatomyScanOutcomeSchema.ts @@ -0,0 +1,23 @@ +import { z } from "zod/v4"; +import { AnatomyDiagnosticSchema } from "./AnatomyDiagnosticSchema.js"; +import { AnatomyFindingSchema } from "./AnatomyFindingSchema.js"; +export const AnatomyScanOutcomeSchema = z.discriminatedUnion("status", [ + z.strictObject({ + operation: z.literal("check"), + status: z.literal("completed"), + conforms: z.boolean(), + summary: z.strictObject({ + block: z.number(), + warn: z.number(), + allow: z.number(), + }), + issues: z.array(AnatomyFindingSchema), + }), + z.strictObject({ + operation: z.literal("check"), + status: z.literal("error"), + conforms: z.null(), + diagnostics: z.array(AnatomyDiagnosticSchema), + }), +]); +export type AnatomyScanOutcome = z.infer; diff --git a/packages/schemas/src/composition/AnatomyScanRequestSchema.ts b/packages/schemas/src/composition/AnatomyScanRequestSchema.ts new file mode 100644 index 0000000..87ed5a6 --- /dev/null +++ b/packages/schemas/src/composition/AnatomyScanRequestSchema.ts @@ -0,0 +1,16 @@ +import { z } from "zod/v4"; +import { AnatomyTargetSchema } from "./AnatomyTargetSchema.js"; +export const AnatomyScanRequestSchema = z.strictObject({ + bundle: z.unknown(), + target: AnatomyTargetSchema, + coverage: z.discriminatedUnion("status", [ + z.strictObject({ status: z.literal("complete") }), + z.strictObject({ + status: z.literal("incomplete"), + reason: z.string(), + paths: z.array(z.string()), + }), + ]), + sources: z.record(z.string(), z.string()).optional(), +}); +export type AnatomyScanRequest = z.infer; diff --git a/packages/schemas/src/composition/AnatomyTargetSchema.ts b/packages/schemas/src/composition/AnatomyTargetSchema.ts new file mode 100644 index 0000000..2ac51ce --- /dev/null +++ b/packages/schemas/src/composition/AnatomyTargetSchema.ts @@ -0,0 +1,15 @@ +import { z } from "zod/v4"; +const file = z.strictObject({ + kind: z.literal("file"), + name: z.string().min(1), +}); +export const AnatomyTargetSchema = z.strictObject({ + kind: z.literal("directory"), + name: z.string().min(1), + get children(): z.ZodArray< + z.ZodUnion<[typeof file, typeof AnatomyTargetSchema]> + > { + return z.array(z.union([file, AnatomyTargetSchema])); + }, +}); +export type AnatomyTarget = z.infer; diff --git a/packages/schemas/src/composition/index.ts b/packages/schemas/src/composition/index.ts new file mode 100644 index 0000000..262b3a9 --- /dev/null +++ b/packages/schemas/src/composition/index.ts @@ -0,0 +1,14 @@ +export * from "./AnatomyBundleQueryOutcomeSchema.js"; +export * from "./AnatomyBundleQueryRequestSchema.js"; +export * from "./AnatomyBundleSchema.js"; +export * from "./AnatomyBundleValidationOutcomeSchema.js"; +export * from "./AnatomyCompositionNodeSchema.js"; +export * from "./AnatomyDefinitionSchema.js"; +export * from "./AnatomyDiagnosticSchema.js"; +export * from "./AnatomyFindingSchema.js"; +export * from "./AnatomyMountSchema.js"; +export * from "./AnatomyRuleSchema.js"; +export * from "./AnatomyOriginSchema.js"; +export * from "./AnatomyScanOutcomeSchema.js"; +export * from "./AnatomyScanRequestSchema.js"; +export * from "./AnatomyTargetSchema.js"; diff --git a/packages/schemas/src/index.ts b/packages/schemas/src/index.ts index c5f8d14..18631f4 100644 --- a/packages/schemas/src/index.ts +++ b/packages/schemas/src/index.ts @@ -1 +1,2 @@ -export * from "./anatomy"; +export * from "./anatomy/index.js"; +export * from "./composition/index.js"; diff --git a/packages/schemas/tsconfig.build.json b/packages/schemas/tsconfig.build.json new file mode 100644 index 0000000..5b5e90e --- /dev/null +++ b/packages/schemas/tsconfig.build.json @@ -0,0 +1,17 @@ +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "noEmit": false, + "declaration": true, + "declarationMap": false, + "rootDir": "src", + "outDir": "dist", + "paths": {} + }, + "include": [ + "src" + ], + "exclude": [ + "src/**/*.spec.ts" + ] +} diff --git a/packages/schemas/tsconfig.json b/packages/schemas/tsconfig.json index 63586b9..cf45886 100644 --- a/packages/schemas/tsconfig.json +++ b/packages/schemas/tsconfig.json @@ -11,7 +11,12 @@ "resolveJsonModule": true, "isolatedModules": true, "noEmit": true, - "types": ["node"] + "types": [ + "node" + ] }, - "include": ["src"] + "include": [ + "src" + ], + "extends": "../../tsconfig.json" } diff --git a/tsconfig.json b/tsconfig.json index 021d582..0d3487b 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -11,7 +11,32 @@ "resolveJsonModule": true, "isolatedModules": true, "noEmit": true, - "types": ["node"] + "types": [ + "node" + ], + "paths": { + "@anatomy-cli/anatomy/core": [ + "./packages/anatomy/src/core/index.ts" + ], + "@anatomy-cli/anatomy/source": [ + "./packages/anatomy/src/source/index.ts" + ], + "@anatomy-cli/anatomy/composition": [ + "./packages/anatomy/src/composition/index.ts" + ], + "@anatomy-cli/anatomy": [ + "./packages/anatomy/src/index.ts" + ], + "@anatomy-cli/schemas/anatomy": [ + "./packages/schemas/src/anatomy/index.ts" + ], + "@anatomy-cli/schemas/composition": [ + "./packages/schemas/src/composition/index.ts" + ], + "@anatomy-cli/schemas": [ + "./packages/schemas/src/index.ts" + ] + } }, "include": [ "apps/anatomy-cli/src", diff --git a/vitest.config.ts b/vitest.config.ts index 04cd9be..31d9de1 100644 --- a/vitest.config.ts +++ b/vitest.config.ts @@ -1,6 +1,55 @@ import { defineConfig } from "vitest/config"; export default defineConfig({ + resolve: { + alias: [ + { + find: "@anatomy-cli/anatomy/core", + replacement: new URL( + "./packages/anatomy/src/core/index.ts", + import.meta.url, + ).pathname, + }, + { + find: "@anatomy-cli/anatomy/source", + replacement: new URL( + "./packages/anatomy/src/source/index.ts", + import.meta.url, + ).pathname, + }, + { + find: "@anatomy-cli/anatomy/composition", + replacement: new URL( + "./packages/anatomy/src/composition/index.ts", + import.meta.url, + ).pathname, + }, + { + find: "@anatomy-cli/anatomy", + replacement: new URL("./packages/anatomy/src/index.ts", import.meta.url) + .pathname, + }, + { + find: "@anatomy-cli/schemas/anatomy", + replacement: new URL( + "./packages/schemas/src/anatomy/index.ts", + import.meta.url, + ).pathname, + }, + { + find: "@anatomy-cli/schemas/composition", + replacement: new URL( + "./packages/schemas/src/composition/index.ts", + import.meta.url, + ).pathname, + }, + { + find: "@anatomy-cli/schemas", + replacement: new URL("./packages/schemas/src/index.ts", import.meta.url) + .pathname, + }, + ], + }, test: { globals: true, include: ["**/*.spec.ts"], From 579d313de75e45d29afdda6c5d3507f617f9070f Mon Sep 17 00:00:00 2001 From: Zander Zhang <276678881@qq.com> Date: Tue, 15 Sep 2026 16:35:09 +0800 Subject: [PATCH 5/8] feat: automate patch and canary npm releases --- .github/workflows/publish-npm.yml | 87 +++++ README.md | 42 ++- README.zh-CN.md | 27 +- anatomy.coverage.json | 17 + anatomy.json | 50 +++ .../anatomies/cli-source.anatomy.json | 43 +++ apps/anatomy-cli/src/NpmReleaseError.ts | 6 + apps/anatomy-cli/src/npm-release.spec.ts | 101 ++++++ apps/anatomy-cli/src/planNpmRelease.ts | 70 ++++ apps/anatomy-cli/src/release-main.ts | 7 + apps/anatomy-cli/src/runNpmRelease.ts | 331 ++++++++++++++++++ 11 files changed, 764 insertions(+), 17 deletions(-) create mode 100644 .github/workflows/publish-npm.yml create mode 100644 apps/anatomy-cli/src/NpmReleaseError.ts create mode 100644 apps/anatomy-cli/src/npm-release.spec.ts create mode 100644 apps/anatomy-cli/src/planNpmRelease.ts create mode 100644 apps/anatomy-cli/src/release-main.ts create mode 100644 apps/anatomy-cli/src/runNpmRelease.ts diff --git a/.github/workflows/publish-npm.yml b/.github/workflows/publish-npm.yml new file mode 100644 index 0000000..c57cc89 --- /dev/null +++ b/.github/workflows/publish-npm.yml @@ -0,0 +1,87 @@ +name: Publish npm packages +run-name: npm ${{ inputs.channel || (startsWith(github.ref, 'refs/tags/canary-') && 'canary' || 'stable') }} from ${{ github.ref_name }} + +on: + push: + branches: [main] + tags: ['canary-*'] + paths: + - 'apps/anatomy-cli/**' + - 'packages/anatomy/**' + - 'packages/schemas/**' + - 'package.json' + - 'bun.lock' + - 'tsconfig.json' + - '.nvmrc' + - '.github/workflows/publish-npm.yml' + workflow_dispatch: + inputs: + channel: + description: 'stable increments 0.0.x; canary publishes only to the canary tag' + type: choice + options: [stable, canary] + default: stable + required: true + +permissions: + contents: read + +concurrency: + group: npm-publication + cancel-in-progress: false + +jobs: + publish: + if: github.repository == 'forge-town/anatomy-cli' + runs-on: ubuntu-latest + timeout-minutes: 20 + permissions: + contents: read + id-token: write + env: + RELEASE_CHANNEL: ${{ inputs.channel || (startsWith(github.ref, 'refs/tags/canary-') && 'canary' || 'stable') }} + steps: + - uses: actions/checkout@v4 + - uses: oven-sh/setup-bun@v2 + with: + bun-version: 1.3.11 + - uses: actions/setup-node@v4 + with: + node-version-file: .nvmrc + registry-url: https://registry.npmjs.org + - name: Validate channel and publication credentials + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + run: | + if [ "$RELEASE_CHANNEL" = stable ] && [ "$GITHUB_REF" != refs/heads/main ]; then + echo '::error::Stable releases must run from main. Select channel=canary for a branch.' + exit 1 + fi + if [ -z "$NODE_AUTH_TOKEN" ]; then + echo '::error::Configure NPM_TOKEN with publish access to anatomy-cli, @anatomy-cli/schemas, and @anatomy-cli/anatomy.' + exit 1 + fi + npm whoami --registry=https://registry.npmjs.org + - run: bun install --frozen-lockfile + - name: Test and build the source snapshot + run: bun run quality + - name: Prepare the next patch and verify packed consumers + run: bun apps/anatomy-cli/src/release-main.ts prepare + - name: Publish and verify registry consumers + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + run: bun apps/anatomy-cli/src/release-main.ts publish + - name: Upload release plan, tarballs, and verification results + if: always() + uses: actions/upload-artifact@v4 + with: + name: npm-release-${{ github.run_id }}-${{ github.run_attempt }} + path: | + docs/verification/npm-release/artifacts/release-plan.json + docs/verification/npm-release/artifacts/*.tgz + docs/verification/npm-release/artifacts/*-consumer.json + if-no-files-found: ignore + - name: Summarize the verified release + run: | + echo '### Published and installed successfully' >> "$GITHUB_STEP_SUMMARY" + cat docs/verification/npm-release/artifacts/registry-consumer.json >> "$GITHUB_STEP_SUMMARY" diff --git a/README.md b/README.md index dabcf6d..beb5dda 100644 --- a/README.md +++ b/README.md @@ -353,23 +353,41 @@ outside this workspace and is not modified by this project. ## Publishing -The one-shot installer must be published in a new `anatomy-cli` release before -the registry commands above gain this behavior; the existing 0.0.2 release -predates it. Do not deploy homepage installer instructions ahead of that release. +`Publish npm packages` automatically publishes a stable patch when release-related +changes reach `main`. All three public packages share the next `0.0.x` version: +`@anatomy-cli/schemas`, `@anatomy-cli/anatomy`, then `anatomy-cli`. The root package +stays private. Minor and major releases are disabled until explicitly enabled. -The root package is intentionally private. To publish a CLI release, authenticate -with npm and publish the app workspace with Bun. Build the workspace first; the -prepack hook creates the CLI declarations and Node.js bundles: +Configure the repository Actions secret `NPM_TOKEN` with non-interactive publish +access to all three packages (including permission to create the scoped packages). +The workflow uses Node from `.nvmrc`, runs `bun run quality`, installs the packed +CLI and SDK in an isolated consumer, then publishes with provenance. It reads +back registry versions, integrity and tags, and installs the published packages +again. Release plans, tarballs and consumer results are uploaded as run artifacts. + +To publish a canary manually after the workflow reaches `main`: ```bash -cd apps/anatomy-cli -bun publish --access public +gh workflow run publish-npm.yml --ref main -f channel=canary ``` -The package's `bin` entries must stay distinct: `anatomy-cli` dispatches to the -installer by default; `anatomy` dispatches to the checker. Publish the three -bundles (`main.js`, `index.js`, `install-main.js`) and the `bin/` launchers -together. No separate installer package or install lifecycle script is needed. +The Actions UI also accepts `channel=stable` (the default) or `channel=canary`. +Stable runs require `main`; canaries can use a feature branch. Before the workflow +is on the default branch, pushing a `canary-*` Git tag triggers a canary from that +commit. Canary versions look like `0.0.4-canary..` and update only +the npm `canary` tag. Install them with `npm install anatomy-cli@canary` or +`npm install @anatomy-cli/anatomy@canary @anatomy-cli/schemas@canary`. + +Stable version numbers come from the highest registry `0.0.x` patch across the +three packages. A stable retry resumes the same source version instead of bumping +again; conflicting published artifacts fail. Versions and internal dependency +pins are changed only in staged package copies under ignored root `docs/`. +The workflow does not commit version changes; registry metadata records the +published version and source commit. Canary runs do not advance `latest`. + +The package's `bin` entries stay distinct: `anatomy-cli` dispatches to the installer; +`anatomy` dispatches to the checker. The release includes the CLI bundles and +`bin/` launchers together. ## Composition bundles and the SDK diff --git a/README.zh-CN.md b/README.zh-CN.md index e06d59b..d072d89 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -241,16 +241,33 @@ bun run build ## 发布 -必须先发布包含一键安装器的新 `anatomy-cli` 版本,上面的包仓库安装命令才会具有对应行为。现有 `0.0.2` 版本发布于该功能之前。请勿在新版发布前部署包含一键安装说明的首页。 +`Publish npm packages` 在发版相关改动进入 `main` 后自动发布 patch。目前只递增 +`0.0.x` 的第三位,不自动升级 minor 或 major。三个公开包使用同一版本,按 +`@anatomy-cli/schemas` → `@anatomy-cli/anatomy` → `anatomy-cli` 的顺序发布;根包保持私有。 -根包有意设置为私有。发布 CLI 时,先构建工作区并登录 npm,再使用 Bun 发布应用工作区;`prepack` 钩子会生成 CLI 类型声明和 Node.js 构建文件: +先在仓库 Actions Secrets 配置 `NPM_TOKEN`,授予三个包的无交互发布权限,首次发布 +还需要创建 scope 包的权限。工作流使用 `.nvmrc` 中的 Node,运行 `bun run quality`, +独立安装打包后的 CLI 和 SDK 验证,再携带 provenance 发布。发布后回读 registry 的版本、 +完整性和标签,并重新安装验证。版本计划、tarball 和消费验证结果保存在 Actions artifacts。 + +工作流进入 `main` 后,可以手动发布 canary: ```bash -cd apps/anatomy-cli -bun publish --access public +gh workflow run publish-npm.yml --ref main -f channel=canary ``` -包的两个 `bin` 入口必须保持独立:`anatomy-cli` 默认进入安装器,`anatomy` 进入检查器。发布时应同时包含三个构建文件(`main.js`、`index.js`、`install-main.js`)和 `bin/` 下的启动文件。无需单独的安装器包或安装生命周期脚本。 +Actions 页面也支持选择 `channel=stable`(默认)或 `channel=canary`。稳定版只允许从 +`main` 发布;canary 可以选择功能分支。工作流尚未进入默认分支时,推送 `canary-*` Git +标签也能从对应提交触发 canary。版本形如 `0.0.4-canary..`,只更新 npm +的 `canary` 标签,不更新 `latest`。安装命令为 `npm install anatomy-cli@canary`,SDK 为 +`npm install @anatomy-cli/anatomy@canary @anatomy-cli/schemas@canary`。 + +稳定版取三个包在 registry 上最高的 `0.0.x` 再递增。同一源码提交的稳定版重跑会继续原版本, +不会重复递增;已发布产物冲突时失败。版本号和内部依赖精确版本只写入被忽略的根 `docs/` +下的临时打包副本,工作流不向 Git 提交版本修改,实际发布版本与源码提交以 registry 为准。 + +两个 `bin` 入口保持独立:`anatomy-cli` 默认进入安装器,`anatomy` 进入检查器。 +发布产物同时包含 CLI 构建文件和 `bin/` 启动文件。 ## 组合 Bundle 与 SDK diff --git a/anatomy.coverage.json b/anatomy.coverage.json index 182eb4b..591797d 100644 --- a/anatomy.coverage.json +++ b/anatomy.coverage.json @@ -921,6 +921,23 @@ "runtimeExports": [ "AnatomyRuleSchema" ] + }, + "apps/anatomy-cli/src/npm-release.spec.ts": { + "role": "test", + "reason": "Executable regression suite with no public runtime exports.", + "runtimeExports": [] + }, + "apps/anatomy-cli/src/NpmReleaseError.ts": { + "role": "class", + "reason": "Dedicated release error class.", + "runtimeExports": [ + "NpmReleaseError" + ] + }, + "apps/anatomy-cli/src/release-main.ts": { + "role": "entrypoint", + "reason": "GitHub Actions release process entrypoint; no public runtime exports.", + "runtimeExports": [] } } } diff --git a/anatomy.json b/anatomy.json index b2ea91a..44e3168 100644 --- a/anatomy.json +++ b/anatomy.json @@ -30,6 +30,13 @@ "kind": "file", "name": { "type": "literal", "value": "deploy-docs.yml" }, "quantity": "exactly_one" + }, + { + "id": "a7082281-d14e-47e3-9676-d33b35803497", + "kind": "file", + "name": { "type": "literal", "value": "publish-npm.yml" }, + "quantity": "exactly_one", + "policyOverrides": {} } ] } @@ -440,6 +447,49 @@ "name": "file_stem", "policy": "block" } + }, + { + "id": "2bd1e035-6adf-4c66-b914-c39d13534ab9", + "kind": "file", + "name": { "type": "literal", "value": "NpmReleaseError.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "c9628cc1-0955-494c-bcc8-3d7dbfeb7f77", + "kind": "file", + "name": { "type": "literal", "value": "npm-release.spec.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "4a897b3f-4fa5-4fd0-94c2-e674b8c40c68", + "kind": "file", + "name": { "type": "literal", "value": "planNpmRelease.ts" }, + "quantity": "exactly_one", + "policyOverrides": {}, + "exports": { + "name": "file_stem", + "policy": "block" + } + }, + { + "id": "e24d00a1-6a21-4c36-b524-0c0710a510b3", + "kind": "file", + "name": { "type": "literal", "value": "release-main.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "f6b731f4-7d53-40a9-a0e7-d085b366f5d2", + "kind": "file", + "name": { "type": "literal", "value": "runNpmRelease.ts" }, + "quantity": "exactly_one", + "policyOverrides": {}, + "exports": { + "name": "file_stem", + "policy": "block" + } } ] }, diff --git a/apps/anatomy-cli/anatomies/cli-source.anatomy.json b/apps/anatomy-cli/anatomies/cli-source.anatomy.json index 0f9cd0c..42977b7 100644 --- a/apps/anatomy-cli/anatomies/cli-source.anatomy.json +++ b/apps/anatomy-cli/anatomies/cli-source.anatomy.json @@ -307,6 +307,49 @@ "name": "file_stem", "policy": "block" } + }, + { + "id": "2bd1e035-6adf-4c66-b914-c39d13534ab9", + "kind": "file", + "name": { "type": "literal", "value": "NpmReleaseError.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "c9628cc1-0955-494c-bcc8-3d7dbfeb7f77", + "kind": "file", + "name": { "type": "literal", "value": "npm-release.spec.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "4a897b3f-4fa5-4fd0-94c2-e674b8c40c68", + "kind": "file", + "name": { "type": "literal", "value": "planNpmRelease.ts" }, + "quantity": "exactly_one", + "policyOverrides": {}, + "exports": { + "name": "file_stem", + "policy": "block" + } + }, + { + "id": "e24d00a1-6a21-4c36-b524-0c0710a510b3", + "kind": "file", + "name": { "type": "literal", "value": "release-main.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "f6b731f4-7d53-40a9-a0e7-d085b366f5d2", + "kind": "file", + "name": { "type": "literal", "value": "runNpmRelease.ts" }, + "quantity": "exactly_one", + "policyOverrides": {}, + "exports": { + "name": "file_stem", + "policy": "block" + } } ] } diff --git a/apps/anatomy-cli/src/NpmReleaseError.ts b/apps/anatomy-cli/src/NpmReleaseError.ts new file mode 100644 index 0000000..74c1fd1 --- /dev/null +++ b/apps/anatomy-cli/src/NpmReleaseError.ts @@ -0,0 +1,6 @@ +export class NpmReleaseError extends Error { + constructor(message: string) { + super(message); + this.name = "NpmReleaseError"; + } +} diff --git a/apps/anatomy-cli/src/npm-release.spec.ts b/apps/anatomy-cli/src/npm-release.spec.ts new file mode 100644 index 0000000..9aeeddf --- /dev/null +++ b/apps/anatomy-cli/src/npm-release.spec.ts @@ -0,0 +1,101 @@ +import { describe, expect, it } from "vitest"; +import { readFileSync } from "node:fs"; +import { planNpmRelease, type NpmPackageHistory } from "./planNpmRelease.js"; +const sha = "a".repeat(40); +const history = (): NpmPackageHistory[] => [ + { name: "@anatomy-cli/schemas", versions: {}, tags: {} }, + { name: "@anatomy-cli/anatomy", versions: {}, tags: {} }, + { + name: "anatomy-cli", + versions: { "0.0.3": { gitHead: "b".repeat(40) } }, + tags: { latest: "0.0.3" }, + }, +]; +describe("patch-only npm release planning", () => { + it("starts unpublished SDK packages on the CLI's next patch", () => { + expect( + planNpmRelease(history(), sha, "stable", "12", "1")._unsafeUnwrap(), + ).toMatchObject({ version: "0.0.4", tag: "latest" }); + }); + it("keeps canaries off latest and does not consume stable patch numbers", () => { + const h = history(); + h[2]!.versions["0.0.99-canary.10.1"] = { gitHead: sha }; + expect( + planNpmRelease(h, sha, "canary", "12", "2")._unsafeUnwrap(), + ).toMatchObject({ version: "0.0.4-canary.12.2", tag: "canary" }); + expect( + planNpmRelease(h, sha, "stable", "12", "2")._unsafeUnwrap().version, + ).toBe("0.0.4"); + }); + it("resumes a partially published stable version instead of incrementing again", () => { + const h = history(); + h[0]!.versions["0.0.4"] = { gitHead: sha }; + expect( + planNpmRelease(h, sha, "stable", "12", "2")._unsafeUnwrap().version, + ).toBe("0.0.4"); + }); + it("does not release a newer patch again for the same source", () => { + const h = history(); + for (const p of h) p.versions["0.0.4"] = { gitHead: sha }; + expect( + planNpmRelease(h, sha, "stable", "13", "1")._unsafeUnwrap().version, + ).toBe("0.0.4"); + }); + it("refuses to roll latest back to an older source", () => { + const h = history(); + h[0]!.versions["0.0.2"] = { gitHead: sha }; + expect(planNpmRelease(h, sha, "stable", "1", "1").isErr()).toBe(true); + }); + it("rejects inconsistent versions for one source", () => { + const h = history(); + h[0]!.versions["0.0.4"] = { gitHead: sha }; + h[1]!.versions["0.0.5"] = { gitHead: sha }; + expect(planNpmRelease(h, sha, "stable", "1", "1").isErr()).toBe(true); + }); + it("never automatically crosses to a minor release", () => { + const h = history(); + h[0]!.versions["0.1.0"] = {}; + expect(planNpmRelease(h, sha, "stable", "1", "1").isErr()).toBe(true); + }); + it.each(["minor", "major", "canary; echo bad"])( + "rejects unsupported channel %s", + (channel) => { + expect(planNpmRelease(history(), sha, channel, "1", "1").isErr()).toBe( + true, + ); + }, + ); + it.each([ + ["bad", "1", "1"], + [sha, "bad", "1"], + [sha, "1", "bad"], + ])("rejects malformed run identity", (source, run, attempt) => { + expect( + planNpmRelease(history(), source, "canary", run, attempt).isErr(), + ).toBe(true); + }); + it("requires a complete package set", () => { + expect( + planNpmRelease(history().slice(1), sha, "stable", "1", "1").isErr(), + ).toBe(true); + }); + it("does not add a canary build or retry to the stable counter", () => { + const h = history(); + h[2]!.versions["0.0.9"] = {}; + expect( + planNpmRelease(h, sha, "canary", "999", "2")._unsafeUnwrap().version, + ).toBe("0.0.10-canary.999.2"); + }); + it("publishes only through explicit main or canary triggers and isolates the token", () => { + const workflow = readFileSync( + new URL("../../../.github/workflows/publish-npm.yml", import.meta.url), + "utf8", + ); + expect(workflow).toContain("branches: [main]"); + expect(workflow).toContain("tags: ['canary-*']"); + expect(workflow).toContain("cancel-in-progress: false"); + expect(workflow).not.toContain("pull_request_target"); + expect(workflow).not.toContain("pull_request:"); + expect(workflow).toContain("bun run quality"); + }); +}); diff --git a/apps/anatomy-cli/src/planNpmRelease.ts b/apps/anatomy-cli/src/planNpmRelease.ts new file mode 100644 index 0000000..314df4a --- /dev/null +++ b/apps/anatomy-cli/src/planNpmRelease.ts @@ -0,0 +1,70 @@ +import { err, ok } from "neverthrow"; +import { NpmReleaseError } from "./NpmReleaseError.js"; + +export type NpmPackageHistory = { + name: string; + versions: Record; + tags: Record; +}; + +export const planNpmRelease = ( + histories: NpmPackageHistory[], + source: string, + channel: string, + runId: string, + attempt: string, +) => { + if (!/^[a-f0-9]{40}$/.test(source) || !["stable", "canary"].includes(channel)) + return err( + new NpmReleaseError("Invalid source revision or release channel"), + ); + if (!/^\d+$/.test(runId) || !/^\d+$/.test(attempt)) + return err(new NpmReleaseError("Release run and attempt must be numeric")); + if ( + histories.length !== 3 || + new Set(histories.map((p) => p.name)).size !== 3 + ) + return err( + new NpmReleaseError("A release requires all three distinct packages"), + ); + let highest = 0; + const sameSource = new Set(); + for (const history of histories) { + for (const [version, record] of Object.entries(history.versions)) { + if (!/^\d+\.\d+\.\d+$/.test(version)) continue; + if (!/^0\.0\.\d+$/.test(version)) + return err( + new NpmReleaseError( + `${history.name}: only the 0.0.x release line is enabled`, + ), + ); + highest = Math.max(highest, Number(version.split(".")[2])); + if (record.gitHead === source) sameSource.add(version); + } + } + if (sameSource.size > 1) + return err( + new NpmReleaseError("Source revision has conflicting stable versions"), + ); + const previous = [...sameSource][0]; + if ( + channel === "stable" && + previous && + Number(previous.split(".")[2]) < highest + ) + return err( + new NpmReleaseError( + "Refusing to restore latest to an older source release", + ), + ); + const base = + channel === "stable" && previous ? previous : `0.0.${highest + 1}`; + const version = + channel === "canary" ? `${base}-canary.${runId}.${attempt}` : base; + return ok({ + version, + tag: channel === "canary" ? "canary" : "latest", + source, + channel, + }); +}; diff --git a/apps/anatomy-cli/src/release-main.ts b/apps/anatomy-cli/src/release-main.ts new file mode 100644 index 0000000..08be814 --- /dev/null +++ b/apps/anatomy-cli/src/release-main.ts @@ -0,0 +1,7 @@ +import { runNpmRelease } from "./runNpmRelease.js"; + +const result = await runNpmRelease(process.argv[2] ?? "prepare"); +if (result.isErr()) { + console.error(result.error.message); + process.exitCode = 1; +} diff --git a/apps/anatomy-cli/src/runNpmRelease.ts b/apps/anatomy-cli/src/runNpmRelease.ts new file mode 100644 index 0000000..441698d --- /dev/null +++ b/apps/anatomy-cli/src/runNpmRelease.ts @@ -0,0 +1,331 @@ +import { execFile } from "node:child_process"; +import { createHash } from "node:crypto"; +import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises"; +import { join, resolve } from "node:path"; +import { promisify } from "node:util"; +import { ResultAsync } from "neverthrow"; +import { NpmReleaseError } from "./NpmReleaseError.js"; +import { planNpmRelease, type NpmPackageHistory } from "./planNpmRelease.js"; + +export const runNpmRelease = (mode: string) => + ResultAsync.fromPromise( + (async () => { + const root = resolve(import.meta.dirname, "../../.."); + const output = join(root, "docs/verification/npm-release/artifacts"); + const packagePaths = [ + "packages/schemas", + "packages/anatomy", + "apps/anatomy-cli", + ]; + const names = [ + "@anatomy-cli/schemas", + "@anatomy-cli/anatomy", + "anatomy-cli", + ]; + const exec = async (command: string, args: string[], cwd = root) => + ( + await promisify(execFile)(command, args, { + cwd, + maxBuffer: 16 * 1024 * 1024, + }) + ).stdout.trim(); + const source = await exec("git", ["rev-parse", "HEAD"]); + const manifest = async (path: string) => + JSON.parse(await readFile(join(root, path, "package.json"), "utf8")); + const readHistory = async (name: string): Promise => { + const response = await fetch( + `https://registry.npmjs.org/${encodeURIComponent(name)}`, + { + signal: AbortSignal.timeout(30_000), + headers: { accept: "application/json" }, + }, + ); + if (response.status === 404) return { name, versions: {}, tags: {} }; + if (!response.ok) + throw new NpmReleaseError( + `${name}: registry returned ${response.status}`, + ); + const data = (await response.json()) as { + versions?: NpmPackageHistory["versions"]; + "dist-tags"?: Record; + }; + if (!data.versions || !data["dist-tags"]) + throw new NpmReleaseError(`${name}: malformed registry metadata`); + return { name, versions: data.versions, tags: data["dist-tags"] }; + }; + const checkConsumer = async ( + specifiers: string[], + label: string, + version: string, + ) => { + const consumer = join(output, label); + await rm(consumer, { recursive: true, force: true }); + await mkdir(consumer, { recursive: true }); + await writeFile( + join(consumer, "package.json"), + JSON.stringify({ + name: "anatomy-release-check", + private: true, + type: "module", + }), + ); + await exec( + "npm", + [ + "install", + "--ignore-scripts", + "--no-audit", + "--no-fund", + ...specifiers, + ], + consumer, + ); + await writeFile( + join(consumer, "check.mjs"), + `import { scanAnatomy, queryAnatomyBundle } from '@anatomy-cli/anatomy'; +import { AnatomyScanOutcomeSchema } from '@anatomy-cli/schemas'; +import {createRequire} from 'node:module'; +import {readFileSync} from 'node:fs'; +const require=createRequire(import.meta.url); +for(const name of ${JSON.stringify(names)}) { + const entry=require.resolve(name); + if(!entry.startsWith(process.cwd()+'/node_modules/')) throw Error('Dependency escaped consumer'); + const pkg=JSON.parse(readFileSync('node_modules/'+name+'/package.json','utf8')); + if(pkg.version!==${JSON.stringify(version)}) throw Error('Wrong installed version: '+name); +} +const bundle=${await readFile(join(root, "apps/anatomy-cli/anatomies/db-schema.bundle.json"), "utf8")}; +const f=name=>({kind:'file',name});const d=(name,children)=>({kind:'directory',name,children}); +const target=d('db-schema',[f('package.json'),f('tsconfig.json'),d('src',[f('index.ts'),d('tables',[f('index.ts'),d('accounts',[f('index.ts'),f('users.table.ts')])]),d('relations',[f('index.ts')])])]); +const result=await scanAnatomy({bundle,target,coverage:{status:'complete'}}); +AnatomyScanOutcomeSchema.parse(result); +if(!result.conforms) throw Error(JSON.stringify(result)); +const q=queryAnatomyBundle({bundle,path:'src/tables/accounts'}); +if(q.status!=='resolved'||q.rules.length!==2)throw Error('Mount query failed'); +console.log(JSON.stringify({node:process.version,version:${JSON.stringify(version)},conforms:result.conforms,query:q.status}));`, + ); + const checked = await exec("node", ["check.mjs"], consumer); + const help = await exec( + "node", + ["node_modules/anatomy-cli/bin/anatomy.js", "--help"], + consumer, + ); + if (!help.includes("--bundle")) + throw new NpmReleaseError("Installed CLI does not expose --bundle"); + await writeFile( + join(consumer, "check.ts"), + "import {scanAnatomy} from '@anatomy-cli/anatomy';\nimport type {AnatomyScanOutcome} from '@anatomy-cli/schemas';\nconst result: Promise = scanAnatomy({});\nvoid result;\n", + ); + await exec( + "node", + [ + "node_modules/typescript/bin/tsc", + "--noEmit", + "--strict", + "--skipLibCheck", + "--target", + "ES2022", + "--module", + "NodeNext", + "--moduleResolution", + "NodeNext", + "check.ts", + ], + consumer, + ); + await writeFile(join(output, `${label}.json`), checked + "\n"); + }; + if (mode === "prepare") { + await mkdir(output, { recursive: true }); + const channel = process.env.RELEASE_CHANNEL ?? "stable"; + const plan = planNpmRelease( + await Promise.all(names.map(readHistory)), + source, + channel, + process.env.GITHUB_RUN_ID ?? "0", + process.env.GITHUB_RUN_ATTEMPT ?? "1", + ); + if (plan.isErr()) throw plan.error; + const packages = []; + for (const path of packagePaths) { + const pkg = await manifest(path); + pkg.version = plan.value.version; + pkg.gitHead = source; + pkg.repository = { + type: "git", + url: "git+https://github.com/forge-town/anatomy-cli.git", + directory: path, + }; + for (const key of [ + "dependencies", + "devDependencies", + "peerDependencies", + "optionalDependencies", + ]) { + for (const name of Object.keys(pkg[key] ?? {})) + if (names.includes(name)) pkg[key][name] = plan.value.version; + } + const staging = join( + output, + "packages", + pkg.name.replaceAll("/", "-"), + ); + await rm(staging, { recursive: true, force: true }); + await mkdir(staging, { recursive: true }); + for (const item of pkg.files) + await cp(join(root, path, item), join(staging, item), { + recursive: true, + }); + await writeFile( + join(staging, "package.json"), + JSON.stringify(pkg, null, 2) + "\n", + ); + const packed = JSON.parse( + await exec( + "npm", + [ + "pack", + "--ignore-scripts", + "--json", + "--pack-destination", + output, + ], + staging, + ), + )[0]; + const tarball = join(output, packed.filename); + const integrity = + "sha512-" + + createHash("sha512") + .update(await readFile(tarball)) + .digest("base64"); + packages.push({ + name: pkg.name as string, + filename: packed.filename as string, + integrity, + }); + } + const document = { ...plan.value, packages }; + await writeFile( + join(output, "release-plan.json"), + JSON.stringify(document, null, 2) + "\n", + ); + await checkConsumer( + packages.map((p) => join(output, p.filename)), + "packed-consumer", + document.version, + ); + console.log(JSON.stringify(document, null, 2)); + return; + } + if (!["publish", "verify"].includes(mode)) + throw new NpmReleaseError("Expected prepare, publish, or verify"); + const plan = JSON.parse( + await readFile(join(output, "release-plan.json"), "utf8"), + ) as { + source: string; + version: string; + tag: string; + channel: string; + packages: { name: string; filename: string; integrity: string }[]; + }; + if ( + plan.source !== source || + plan.packages.map((p) => p.name).join() !== names.join() + ) + throw new NpmReleaseError( + "Release plan does not match the checked-out source and packages", + ); + if ( + (plan.channel === "canary" && plan.tag !== "canary") || + (plan.channel === "stable" && plan.tag !== "latest") || + !["stable", "canary"].includes(plan.channel) + ) + throw new NpmReleaseError("Invalid release channel/tag pair"); + if (mode === "publish") { + if (process.env.GITHUB_ACTIONS !== "true") + throw new NpmReleaseError("Publication must run in GitHub Actions"); + if ( + plan.channel === "stable" && + process.env.GITHUB_REF !== "refs/heads/main" + ) + throw new NpmReleaseError("Stable publication is restricted to main"); + if (!process.env.NODE_AUTH_TOKEN) + throw new NpmReleaseError( + "Configure the NPM_TOKEN repository secret before publication", + ); + for (const pkg of plan.packages) { + const tarball = join(output, pkg.filename); + const integrity = + "sha512-" + + createHash("sha512") + .update(await readFile(tarball)) + .digest("base64"); + if (integrity !== pkg.integrity) + throw new NpmReleaseError(`Tarball changed: ${pkg.name}`); + const history = await readHistory(pkg.name); + const existing = history.versions[plan.version]; + if (existing) { + if ( + existing.gitHead !== source || + existing.dist?.integrity !== integrity + ) + throw new NpmReleaseError( + `Refusing conflicting published version: ${pkg.name}@${plan.version}`, + ); + if (history.tags[plan.tag] !== plan.version) + await exec("npm", [ + "dist-tag", + "add", + `${pkg.name}@${plan.version}`, + plan.tag, + ]); + } else { + console.log( + `Publishing ${pkg.name}@${plan.version} with tag ${plan.tag}`, + ); + await exec("npm", [ + "publish", + tarball, + "--ignore-scripts", + "--access", + "public", + "--tag", + plan.tag, + "--provenance", + ]); + } + } + } + for (const pkg of plan.packages) { + let confirmed = false; + for (let attempt = 0; attempt < 6; attempt++) { + const history = await readHistory(pkg.name); + const published = history.versions[plan.version]; + confirmed = + published?.gitHead === source && + published.dist?.integrity === pkg.integrity && + history.tags[plan.tag] === plan.version; + if (confirmed) break; + await new Promise((resolve) => + setTimeout(resolve, 1000 * 2 ** attempt), + ); + } + if (!confirmed) + throw new NpmReleaseError( + `Registry readback did not confirm ${pkg.name}@${plan.version}`, + ); + } + await checkConsumer( + plan.packages.map((p) => `${p.name}@${plan.version}`), + "registry-consumer", + plan.version, + ); + console.log(`Verified all packages at ${plan.version} (${plan.tag})`); + })(), + (cause) => + cause instanceof NpmReleaseError + ? cause + : new NpmReleaseError( + cause instanceof Error ? cause.message : String(cause), + ), + ); From 1449a1b5a63f2b7ba03b7cdd39760d01741cdaae Mon Sep 17 00:00:00 2001 From: Zander Zhang <276678881@qq.com> Date: Tue, 15 Sep 2026 18:01:31 +0800 Subject: [PATCH 6/8] fix: publish CLI and SDK in one anatomy-cli package --- .github/workflows/publish-npm.yml | 4 +- README.md | 47 ++++++------ README.zh-CN.md | 22 +++--- anatomy.coverage.json | 5 ++ anatomy.json | 18 +++++ .../anatomies/cli-source.anatomy.json | 18 +++++ apps/anatomy-cli/package.json | 16 ++--- apps/anatomy-cli/src/build-main.ts | 9 +++ apps/anatomy-cli/src/index.ts | 24 +------ apps/anatomy-cli/src/npm-release.spec.ts | 25 ++++--- apps/anatomy-cli/src/packed-consumer.spec.ts | 66 +++++++++++------ apps/anatomy-cli/src/planNpmRelease.ts | 9 +-- apps/anatomy-cli/src/resolvePackageImports.ts | 72 +++++++++++++++++++ apps/anatomy-cli/src/runNpmRelease.ts | 39 +++++----- apps/anatomy-cli/tsconfig.build.json | 14 ++-- bun.lock | 6 +- packages/anatomy/package.json | 8 +-- packages/schemas/package.json | 6 +- 18 files changed, 268 insertions(+), 140 deletions(-) create mode 100644 apps/anatomy-cli/src/build-main.ts create mode 100644 apps/anatomy-cli/src/resolvePackageImports.ts diff --git a/.github/workflows/publish-npm.yml b/.github/workflows/publish-npm.yml index c57cc89..6ed1988 100644 --- a/.github/workflows/publish-npm.yml +++ b/.github/workflows/publish-npm.yml @@ -1,4 +1,4 @@ -name: Publish npm packages +name: Publish anatomy-cli run-name: npm ${{ inputs.channel || (startsWith(github.ref, 'refs/tags/canary-') && 'canary' || 'stable') }} from ${{ github.ref_name }} on: @@ -58,7 +58,7 @@ jobs: exit 1 fi if [ -z "$NODE_AUTH_TOKEN" ]; then - echo '::error::Configure NPM_TOKEN with publish access to anatomy-cli, @anatomy-cli/schemas, and @anatomy-cli/anatomy.' + echo '::error::Configure NPM_TOKEN with publish access to anatomy-cli.' exit 1 fi npm whoami --registry=https://registry.npmjs.org diff --git a/README.md b/README.md index beb5dda..3be1e80 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,9 @@ ## Workspace layout -- `apps/anatomy-cli` — command-line interface and filesystem adapter -- `packages/anatomy` — immutable Anatomy tree utilities and the conformance engine -- `packages/schemas` — runtime-validated Anatomy Draft schemas (the `anatomy` - domain is the public surface of this standalone workspace) +- `apps/anatomy-cli` — the public CLI and SDK package, including the filesystem adapter +- `packages/anatomy` — private workspace for Anatomy tree utilities and the conformance engine +- `packages/schemas` — private workspace for runtime-validated Anatomy Draft schemas - `packages/anatomy-cli-config` — reusable example Anatomy definitions The migration keeps the original boundaries: the Daedalus CLI becomes the app, @@ -353,16 +352,16 @@ outside this workspace and is not modified by this project. ## Publishing -`Publish npm packages` automatically publishes a stable patch when release-related -changes reach `main`. All three public packages share the next `0.0.x` version: -`@anatomy-cli/schemas`, `@anatomy-cli/anatomy`, then `anatomy-cli`. The root package -stays private. Minor and major releases are disabled until explicitly enabled. +`Publish anatomy-cli` automatically publishes a stable patch when release-related +changes reach `main`. Only `anatomy-cli` is published, providing both the CLI and SDK. +Its next version increments the third number in `0.0.x`. Minor and major releases +are disabled until explicitly enabled. The engine and schema workspaces are private; +their compiled code and declarations ship inside `anatomy-cli`. Configure the repository Actions secret `NPM_TOKEN` with non-interactive publish -access to all three packages (including permission to create the scoped packages). -The workflow uses Node from `.nvmrc`, runs `bun run quality`, installs the packed -CLI and SDK in an isolated consumer, then publishes with provenance. It reads -back registry versions, integrity and tags, and installs the published packages +access to `anatomy-cli`. The workflow uses Node from `.nvmrc`, runs `bun run quality`, +installs the packed CLI and SDK in an isolated consumer, then publishes with provenance. It reads +back registry versions, integrity and tags, and installs the published package again. Release plans, tarballs and consumer results are uploaded as run artifacts. To publish a canary manually after the workflow reaches `main`: @@ -375,13 +374,12 @@ The Actions UI also accepts `channel=stable` (the default) or `channel=canary`. Stable runs require `main`; canaries can use a feature branch. Before the workflow is on the default branch, pushing a `canary-*` Git tag triggers a canary from that commit. Canary versions look like `0.0.4-canary..` and update only -the npm `canary` tag. Install them with `npm install anatomy-cli@canary` or -`npm install @anatomy-cli/anatomy@canary @anatomy-cli/schemas@canary`. +the npm `canary` tag. Install `anatomy-cli@canary` for both the CLI and SDK. -Stable version numbers come from the highest registry `0.0.x` patch across the -three packages. A stable retry resumes the same source version instead of bumping -again; conflicting published artifacts fail. Versions and internal dependency -pins are changed only in staged package copies under ignored root `docs/`. +Stable version numbers come from the highest registry `0.0.x` patch of `anatomy-cli`. +A stable retry resumes the same source version instead of bumping again; conflicting +published artifacts fail. The version changes only in a staged package copy under +ignored root `docs/`. The workflow does not commit version changes; registry metadata records the published version and source commit. Canary runs do not advance `latest`. @@ -441,10 +439,11 @@ alternatives, or source rules, and is not supported inside `one_of` alternatives There is one current contract without format-version selectors or historical Anatomy versions. Each request resolves only its supplied definition snapshot. -After building, the public packages expose ESM JavaScript and declarations: +Install `anatomy-cli` to use the SDK. The same package exposes ESM JavaScript, +runtime schemas, and TypeScript declarations: ```ts -import { scanAnatomy, queryAnatomyBundle, validateAnatomyBundle } from '@anatomy-cli/anatomy'; +import { scanAnatomy, queryAnatomyBundle, validateAnatomyBundle } from 'anatomy-cli'; const validation = validateAnatomyBundle(bundle); const result = await scanAnatomy({ @@ -457,8 +456,8 @@ const query = queryAnatomyBundle({ bundle, path: 'src/tables/accounts', targetNa ``` The SDK performs no filesystem, Git, network, or database reads and never executes target -source. Source analysis loads lazily when an export rule requires it. `@anatomy-cli/schemas` -exports runtime schemas and their inferred types. The lower-level `checkAnatomy` +source. Source analysis loads lazily when an export rule requires it. `anatomy-cli` +also exports runtime schemas and their inferred types. The lower-level `checkAnatomy` matcher accepts normalized contents rules and a pre-analyzed source export map. A completed scan returns `status: "completed"`, `conforms`, `summary`, and `issues`. @@ -477,7 +476,7 @@ UTF-8 bytes per source, and 20,000,000 source bytes per request. Exceeding a lim `bun run quality` includes isolated tarball installation and real Node CLI/SDK tests; these tests require npm registry access and retain their consumer fixtures under ignored -root `docs/verification/cod-420/`. Release order is schemas, core, then CLI after checking -scope permissions and registry versions. Publishing is a separate operation. Daedalus +root `docs/verification/cod-420/`. Only `anatomy-cli` is published; check its npm +publish permission and registry version before running the release workflow. Daedalus integration additionally owns permissions, business-ID mapping, complete snapshots, Findings mapping, and passing a selected root Anatomy through MCP scan orchestration. diff --git a/README.zh-CN.md b/README.zh-CN.md index d072d89..236cf4a 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -241,12 +241,11 @@ bun run build ## 发布 -`Publish npm packages` 在发版相关改动进入 `main` 后自动发布 patch。目前只递增 -`0.0.x` 的第三位,不自动升级 minor 或 major。三个公开包使用同一版本,按 -`@anatomy-cli/schemas` → `@anatomy-cli/anatomy` → `anatomy-cli` 的顺序发布;根包保持私有。 +`Publish anatomy-cli` 在发版相关改动进入 `main` 后自动发布 patch。目前只递增 +`0.0.x` 的第三位,不自动升级 minor 或 major。只发布 `anatomy-cli` 一个包,同时提供 CLI、SDK、 +运行时 Schema 和类型。engine 和 schemas 工作区标记为私有,编译产物一起放进 `anatomy-cli`。 -先在仓库 Actions Secrets 配置 `NPM_TOKEN`,授予三个包的无交互发布权限,首次发布 -还需要创建 scope 包的权限。工作流使用 `.nvmrc` 中的 Node,运行 `bun run quality`, +先在仓库 Actions Secrets 配置 `NPM_TOKEN`,只需授予 `anatomy-cli` 的无交互发布权限。工作流使用 `.nvmrc` 中的 Node,运行 `bun run quality`, 独立安装打包后的 CLI 和 SDK 验证,再携带 provenance 发布。发布后回读 registry 的版本、 完整性和标签,并重新安装验证。版本计划、tarball 和消费验证结果保存在 Actions artifacts。 @@ -259,11 +258,10 @@ gh workflow run publish-npm.yml --ref main -f channel=canary Actions 页面也支持选择 `channel=stable`(默认)或 `channel=canary`。稳定版只允许从 `main` 发布;canary 可以选择功能分支。工作流尚未进入默认分支时,推送 `canary-*` Git 标签也能从对应提交触发 canary。版本形如 `0.0.4-canary..`,只更新 npm -的 `canary` 标签,不更新 `latest`。安装命令为 `npm install anatomy-cli@canary`,SDK 为 -`npm install @anatomy-cli/anatomy@canary @anatomy-cli/schemas@canary`。 +的 `canary` 标签,不更新 `latest`。CLI 和 SDK 都通过 `npm install anatomy-cli@canary` 安装。 -稳定版取三个包在 registry 上最高的 `0.0.x` 再递增。同一源码提交的稳定版重跑会继续原版本, -不会重复递增;已发布产物冲突时失败。版本号和内部依赖精确版本只写入被忽略的根 `docs/` +稳定版取 `anatomy-cli` 在 registry 上最高的 `0.0.x` 再递增。同一源码提交的稳定版重跑会继续原版本, +不会重复递增;已发布产物冲突时失败。版本号只写入被忽略的根 `docs/` 下的临时打包副本,工作流不向 Git 提交版本修改,实际发布版本与源码提交以 registry 为准。 两个 `bin` 入口保持独立:`anatomy-cli` 默认进入安装器,`anatomy` 进入检查器。 @@ -301,9 +299,11 @@ Bundle 使用逻辑根键 `root` 和 `definitions: [{ key, definition }]`。key composition 不允许内联 children、alternatives 或源码规则,也不允许出现在 one_of 的 alternatives 中。只维护一套当前契约,不设置格式版本字段或历史 Anatomy 版本;每次请求只使用调用方提供的定义快照。 -构建后的 `@anatomy-cli/anatomy` 提供 `validateAnatomyBundle`、`scanAnatomy`、`queryAnatomyBundle`,`@anatomy-cli/schemas` 提供运行时 Schema 与派生类型。两个包均输出 ESM JavaScript 和 d.ts。调用示例: +安装 `anatomy-cli` 后,即可使用 `validateAnatomyBundle`、`scanAnatomy`、`queryAnatomyBundle`,以及运行时 Schema 与派生类型。这个包同时提供 CLI、ESM JavaScript 和 d.ts。调用示例: ```ts +import { scanAnatomy, queryAnatomyBundle, validateAnatomyBundle } from "anatomy-cli"; + const result = await scanAnatomy({ bundle, target: { kind: 'directory', name: 'db-schema', children: completeTree }, @@ -318,4 +318,4 @@ SDK 不读取文件系统、Git、数据库或网络,不执行目标源码; 公开限额 `AnatomyResourceLimits`:128 个定义、100,000 个输入对象、输入嵌套深度 128、引用深度 32、10,000 个挂载实例、单份源码 5,000,000 UTF-8 字节、全部源码 20,000,000 字节。超限返回 resource_limit_exceeded。 -`bun run quality` 包含打包后独立安装与实际 Node CLI/SDK 测试;测试需要访问 npm registry,消费样例保留在被忽略的根 docs/verification/cod-420/ 中。发布前核对 scope 权限、npm 版本和 schemas→core→CLI 依赖顺序,真正发布是单独操作。Daedalus 仍负责权限、业务 ID 映射、完整仓库快照、Findings 映射,以及 MCP 根 Anatomy 选择与扫描编排的贯通。 +`bun run quality` 包含打包后独立安装与实际 Node CLI/SDK 测试;测试需要访问 npm registry,消费样例保留在被忽略的根 docs/verification/cod-420/ 中。发版工作流只发布 `anatomy-cli`,发布前核对这个包的 npm 权限和版本。Daedalus 仍负责权限、业务 ID 映射、完整仓库快照、Findings 映射,以及 MCP 根 Anatomy 选择与扫描编排的贯通。 diff --git a/anatomy.coverage.json b/anatomy.coverage.json index 591797d..f8befea 100644 --- a/anatomy.coverage.json +++ b/anatomy.coverage.json @@ -938,6 +938,11 @@ "role": "entrypoint", "reason": "GitHub Actions release process entrypoint; no public runtime exports.", "runtimeExports": [] + }, + "apps/anatomy-cli/src/build-main.ts": { + "role": "entrypoint", + "reason": "Package build process entrypoint; no public runtime exports.", + "runtimeExports": [] } } } diff --git a/anatomy.json b/anatomy.json index 44e3168..a77c9f3 100644 --- a/anatomy.json +++ b/anatomy.json @@ -490,6 +490,24 @@ "name": "file_stem", "policy": "block" } + }, + { + "id": "3bd4a3b1-b3cb-48c9-b84e-e04e7bbdf8e3", + "kind": "file", + "name": { "type": "literal", "value": "build-main.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "e8264936-76d8-4532-9712-97c4e3e13022", + "kind": "file", + "name": { "type": "literal", "value": "resolvePackageImports.ts" }, + "quantity": "exactly_one", + "policyOverrides": {}, + "exports": { + "name": "file_stem", + "policy": "block" + } } ] }, diff --git a/apps/anatomy-cli/anatomies/cli-source.anatomy.json b/apps/anatomy-cli/anatomies/cli-source.anatomy.json index 42977b7..6e0c543 100644 --- a/apps/anatomy-cli/anatomies/cli-source.anatomy.json +++ b/apps/anatomy-cli/anatomies/cli-source.anatomy.json @@ -350,6 +350,24 @@ "name": "file_stem", "policy": "block" } + }, + { + "id": "3bd4a3b1-b3cb-48c9-b84e-e04e7bbdf8e3", + "kind": "file", + "name": { "type": "literal", "value": "build-main.ts" }, + "quantity": "exactly_one", + "policyOverrides": {} + }, + { + "id": "e8264936-76d8-4532-9712-97c4e3e13022", + "kind": "file", + "name": { "type": "literal", "value": "resolvePackageImports.ts" }, + "quantity": "exactly_one", + "policyOverrides": {}, + "exports": { + "name": "file_stem", + "policy": "block" + } } ] } diff --git a/apps/anatomy-cli/package.json b/apps/anatomy-cli/package.json index edfaedd..9bd0254 100644 --- a/apps/anatomy-cli/package.json +++ b/apps/anatomy-cli/package.json @@ -1,7 +1,7 @@ { "name": "anatomy-cli", "version": "0.0.2", - "description": "Scan repository file trees against Anatomy Draft definitions.", + "description": "Anatomy CLI and SDK for repository structure and source export validation.", "license": "MIT", "repository": { "type": "git", @@ -32,12 +32,12 @@ }, "exports": { ".": { - "types": "./dist/index.d.ts", - "default": "./dist/index.js" + "types": "./dist/apps/anatomy-cli/src/index.d.ts", + "default": "./dist/apps/anatomy-cli/src/index.js" } }, "scripts": { - "build": "rm -rf dist && tsc -p tsconfig.build.json && bun build src/main.ts --target=node --outfile=dist/main.js && bun build src/index.ts --target=node --outfile=dist/index.js && bun build src/install-main.ts --target=node --outfile=dist/install-main.js", + "build": "rm -rf dist && tsc -p tsconfig.build.json && bun src/build-main.ts && bun build src/main.ts --target=node --outfile=dist/main.js && bun build src/install-main.ts --target=node --outfile=dist/install-main.js", "dev": "bun --watch src/main.ts", "start": "bun src/main.ts", "scan:self": "bun src/main.ts ../.. --git-files", @@ -58,10 +58,10 @@ "typescript": "5.9.2", "vitest": "^4.1.8" }, - "types": "./dist/index.d.ts", + "types": "./dist/apps/anatomy-cli/src/index.d.ts", "dependencies": { - "@anatomy-cli/anatomy": "^0.1.0", - "@anatomy-cli/schemas": "^0.1.0", - "neverthrow": "^8.2.0" + "neverthrow": "^8.2.0", + "zod": "^4.3.6", + "typescript": "5.9.2" } } diff --git a/apps/anatomy-cli/src/build-main.ts b/apps/anatomy-cli/src/build-main.ts new file mode 100644 index 0000000..860c4d1 --- /dev/null +++ b/apps/anatomy-cli/src/build-main.ts @@ -0,0 +1,9 @@ +import { resolvePackageImports } from "./resolvePackageImports.js"; + +const result = await resolvePackageImports( + new URL("../dist", import.meta.url).pathname, +); +if (result.isErr()) { + console.error(result.error.message); + process.exitCode = 1; +} diff --git a/apps/anatomy-cli/src/index.ts b/apps/anatomy-cli/src/index.ts index 5b08504..585ceaa 100644 --- a/apps/anatomy-cli/src/index.ts +++ b/apps/anatomy-cli/src/index.ts @@ -1,22 +1,2 @@ -export * from "./analyzeSourceExports.js"; -export * from "./AnatomyCliArgumentError.js"; -export * from "./AnatomyCliExitCode.js"; -export * from "./AnatomyCliFormatValues.js"; -export * from "./AnatomyCliUsage.js"; -export * from "./AnatomyDefinitionFileError.js"; -export * from "./AnatomyFileTreeError.js"; -export * from "./collectSourceExports.js"; -export * from "./collectFileTree.js"; -export * from "./collectGitFileTree.js"; -export * from "./DefaultAnatomyDefinitionFileName.js"; -export * from "./DefaultIgnoredNames.js"; -export * from "./findAnatomyDefinition.js"; -export * from "./formatAgentCheck.js"; -export * from "./formatAgentError.js"; -export * from "./formatAgentQuery.js"; -export * from "./formatHumanResult.js"; -export * from "./formatJsonResult.js"; -export * from "./parseCliArguments.js"; -export * from "./readAnatomyDefinition.js"; -export * from "./runAnatomyCli.js"; -export * from "./runAnatomyBundleCli.js"; +export * from "../../../packages/anatomy/src/index.js"; +export * from "../../../packages/schemas/src/index.js"; diff --git a/apps/anatomy-cli/src/npm-release.spec.ts b/apps/anatomy-cli/src/npm-release.spec.ts index 9aeeddf..5ed1a25 100644 --- a/apps/anatomy-cli/src/npm-release.spec.ts +++ b/apps/anatomy-cli/src/npm-release.spec.ts @@ -3,8 +3,6 @@ import { readFileSync } from "node:fs"; import { planNpmRelease, type NpmPackageHistory } from "./planNpmRelease.js"; const sha = "a".repeat(40); const history = (): NpmPackageHistory[] => [ - { name: "@anatomy-cli/schemas", versions: {}, tags: {} }, - { name: "@anatomy-cli/anatomy", versions: {}, tags: {} }, { name: "anatomy-cli", versions: { "0.0.3": { gitHead: "b".repeat(40) } }, @@ -12,14 +10,14 @@ const history = (): NpmPackageHistory[] => [ }, ]; describe("patch-only npm release planning", () => { - it("starts unpublished SDK packages on the CLI's next patch", () => { + it("increments the single public package patch", () => { expect( planNpmRelease(history(), sha, "stable", "12", "1")._unsafeUnwrap(), ).toMatchObject({ version: "0.0.4", tag: "latest" }); }); it("keeps canaries off latest and does not consume stable patch numbers", () => { const h = history(); - h[2]!.versions["0.0.99-canary.10.1"] = { gitHead: sha }; + h[0]!.versions["0.0.99-canary.10.1"] = { gitHead: sha }; expect( planNpmRelease(h, sha, "canary", "12", "2")._unsafeUnwrap(), ).toMatchObject({ version: "0.0.4-canary.12.2", tag: "canary" }); @@ -27,7 +25,7 @@ describe("patch-only npm release planning", () => { planNpmRelease(h, sha, "stable", "12", "2")._unsafeUnwrap().version, ).toBe("0.0.4"); }); - it("resumes a partially published stable version instead of incrementing again", () => { + it("resumes a published stable version after verification failed", () => { const h = history(); h[0]!.versions["0.0.4"] = { gitHead: sha }; expect( @@ -49,7 +47,7 @@ describe("patch-only npm release planning", () => { it("rejects inconsistent versions for one source", () => { const h = history(); h[0]!.versions["0.0.4"] = { gitHead: sha }; - h[1]!.versions["0.0.5"] = { gitHead: sha }; + h[0]!.versions["0.0.5"] = { gitHead: sha }; expect(planNpmRelease(h, sha, "stable", "1", "1").isErr()).toBe(true); }); it("never automatically crosses to a minor release", () => { @@ -74,14 +72,23 @@ describe("patch-only npm release planning", () => { planNpmRelease(history(), source, "canary", run, attempt).isErr(), ).toBe(true); }); - it("requires a complete package set", () => { + it("rejects publishing internal or extra packages", () => { expect( - planNpmRelease(history().slice(1), sha, "stable", "1", "1").isErr(), + planNpmRelease( + [ + ...history(), + { name: "@anatomy-cli/schemas", versions: {}, tags: {} }, + ], + sha, + "stable", + "1", + "1", + ).isErr(), ).toBe(true); }); it("does not add a canary build or retry to the stable counter", () => { const h = history(); - h[2]!.versions["0.0.9"] = {}; + h[0]!.versions["0.0.9"] = {}; expect( planNpmRelease(h, sha, "canary", "999", "2")._unsafeUnwrap().version, ).toBe("0.0.10-canary.999.2"); diff --git a/apps/anatomy-cli/src/packed-consumer.spec.ts b/apps/anatomy-cli/src/packed-consumer.spec.ts index 2e3e2bb..ef14b3a 100644 --- a/apps/anatomy-cli/src/packed-consumer.spec.ts +++ b/apps/anatomy-cli/src/packed-consumer.spec.ts @@ -1,6 +1,6 @@ import { existsSync } from "node:fs"; import { execFile } from "node:child_process"; -import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises"; +import { mkdir, mkdtemp, readFile, readdir, writeFile } from "node:fs/promises"; import { resolve, join } from "node:path"; import { promisify } from "node:util"; import { ResultAsync } from "neverthrow"; @@ -22,11 +22,7 @@ beforeAll(async () => { consumer = await mkdtemp(join(root, "docs/verification/cod-420/consumer-")); (await execute("bun", ["run", "build"], root))._unsafeUnwrap(); const tarballs: string[] = []; - for (const pkg of [ - "packages/schemas", - "packages/anatomy", - "apps/anatomy-cli", - ]) { + for (const pkg of ["apps/anatomy-cli"]) { const packed = ( await execute( "npm", @@ -75,11 +71,11 @@ beforeAll(async () => { cliPath = join(consumer, "node_modules/anatomy-cli/bin/anatomy.js"); await writeFile( join(consumer, "sdk.mjs"), - `import {scanAnatomy} from '@anatomy-cli/anatomy'; -import {AnatomyScanOutcomeSchema} from '@anatomy-cli/schemas'; + `import {scanAnatomy} from 'anatomy-cli'; +import {AnatomyScanOutcomeSchema} from 'anatomy-cli'; import {readFileSync} from 'node:fs';import {createRequire} from 'node:module'; const require=createRequire(import.meta.url); -for(const name of ['@anatomy-cli/anatomy','@anatomy-cli/schemas','typescript']) { +for(const name of ['anatomy-cli','typescript']) { if(!require.resolve(name).startsWith(process.cwd()+'/node_modules/')) throw Error('dependency escaped consumer: '+name); } if(Number(process.versions.node.split('.')[0]) < 24) throw Error('Node 24+ required'); @@ -103,16 +99,12 @@ AnatomyScanOutcomeSchema.parse(result);console.log(JSON.stringify(result));`, describe("isolated packed Node consumer", () => { /** @summary Install packages in an ordinary Node consumer * @description - * Given: An isolated consumer uses installed tarballs and runs exclusively through Node. + * Given: An isolated consumer installs only the anatomy-cli tarball and runs exclusively through Node. * When: The maintainer installs and runs the packed consumer example. * Then: ESM imports, type resolution, and CLI bins work without unresolved workspace dependencies. */ it("[AC-28] resolves JavaScript, declarations and manifests", async () => { - for (const pkg of [ - "@anatomy-cli/schemas", - "@anatomy-cli/anatomy", - "anatomy-cli", - ]) { + for (const pkg of ["anatomy-cli"]) { const manifest = await readFile( join(consumer, "node_modules", pkg, "package.json"), "utf8", @@ -122,10 +114,8 @@ describe("isolated packed Node consumer", () => { } await writeFile( join(consumer, "typecheck.ts"), - `import {scanAnatomy,queryAnatomyBundle,validateAnatomyBundle} from '@anatomy-cli/anatomy'; -import type {AnatomyScanOutcome,AnatomyBundleQueryOutcome} from '@anatomy-cli/schemas'; -import {parseCliArguments} from 'anatomy-cli'; -parseCliArguments(['.', '--bundle', 'bundle.json']); + `import {scanAnatomy,queryAnatomyBundle,validateAnatomyBundle} from 'anatomy-cli'; +import type {AnatomyScanOutcome,AnatomyBundleQueryOutcome} from 'anatomy-cli'; const scan: Promise = scanAnatomy({}); const query: AnatomyBundleQueryOutcome = queryAnatomyBundle({}); validateAnatomyBundle({}); void scan; void query;`, @@ -138,7 +128,7 @@ validateAnatomyBundle({}); void scan; void query;`, existsSync( join( consumer, - "node_modules/@anatomy-cli/schemas/dist/anatomy", + "node_modules/anatomy-cli/dist/packages/schemas/src/anatomy", `${obsolete}.js`, ), ), @@ -148,7 +138,7 @@ validateAnatomyBundle({}); void scan; void query;`, existsSync( join( consumer, - "node_modules/@anatomy-cli/schemas/dist/composition/AnatomyNodeV2Schema.js", + "node_modules/anatomy-cli/dist/packages/schemas/src/composition/AnatomyNodeV2Schema.js", ), ), ).toBe(false); @@ -161,7 +151,8 @@ validateAnatomyBundle({}); void scan; void query;`, tsc, "--noEmit", "--strict", - "--skipLibCheck", + "--typeRoots", + "node_modules/@types", "--target", "ES2022", "--module", @@ -176,6 +167,37 @@ validateAnatomyBundle({}); void scan; void query;`, ).toBe(true); const cli = await execute(process.execPath, [cliPath, "--help"], consumer); expect(cli._unsafeUnwrap().stdout).toContain("--bundle"); + }, 30_000); + it("ships the engine and schemas without private npm package dependencies", async () => { + expect(existsSync(join(consumer, "node_modules/@anatomy-cli"))).toBe(false); + const installed = join(consumer, "node_modules/anatomy-cli"); + const manifest = JSON.parse( + await readFile(join(installed, "package.json"), "utf8"), + ); + for (const section of [ + "dependencies", + "peerDependencies", + "optionalDependencies", + ]) + expect( + Object.keys(manifest[section] ?? {}).filter((name) => + name.startsWith("@anatomy-cli/"), + ), + ).toEqual([]); + for (const file of await readdir(join(installed, "dist"), { + recursive: true, + })) { + if (!file.endsWith(".d.ts")) continue; + expect( + await readFile(join(installed, "dist", file), "utf8"), + ).not.toContain("@anatomy-cli/"); + } + for (const name of ["anatomy", "schemas"]) + expect( + JSON.parse( + await readFile(join(root, "packages", name, "package.json"), "utf8"), + ).private, + ).toBe(true); }); /** @summary Scan five definitions from supplied data alone * @description diff --git a/apps/anatomy-cli/src/planNpmRelease.ts b/apps/anatomy-cli/src/planNpmRelease.ts index 314df4a..1aa2c58 100644 --- a/apps/anatomy-cli/src/planNpmRelease.ts +++ b/apps/anatomy-cli/src/planNpmRelease.ts @@ -20,13 +20,8 @@ export const planNpmRelease = ( ); if (!/^\d+$/.test(runId) || !/^\d+$/.test(attempt)) return err(new NpmReleaseError("Release run and attempt must be numeric")); - if ( - histories.length !== 3 || - new Set(histories.map((p) => p.name)).size !== 3 - ) - return err( - new NpmReleaseError("A release requires all three distinct packages"), - ); + if (histories.length !== 1 || histories[0]?.name !== "anatomy-cli") + return err(new NpmReleaseError("Only anatomy-cli may be published")); let highest = 0; const sameSource = new Set(); for (const history of histories) { diff --git a/apps/anatomy-cli/src/resolvePackageImports.ts b/apps/anatomy-cli/src/resolvePackageImports.ts new file mode 100644 index 0000000..727f3db --- /dev/null +++ b/apps/anatomy-cli/src/resolvePackageImports.ts @@ -0,0 +1,72 @@ +import { readFile, readdir, writeFile } from "node:fs/promises"; +import { dirname, join, relative, resolve } from "node:path"; +import { ResultAsync } from "neverthrow"; +import { NpmReleaseError } from "./NpmReleaseError.js"; + +export const resolvePackageImports = (output: string) => + ResultAsync.fromPromise( + (async () => { + const root = resolve(output); + const mappings = new Map(); + for (const name of ["anatomy", "schemas"]) { + const pkg = JSON.parse( + await readFile( + new URL(`../../../packages/${name}/package.json`, import.meta.url), + "utf8", + ), + ); + for (const [key, value] of Object.entries(pkg.exports) as [ + string, + { default: string }, + ][]) { + if (key.includes("*")) continue; + mappings.set( + pkg.name + (key === "." ? "" : key.slice(1)), + join( + root, + "packages", + name, + "src", + value.default.replace("./dist/", ""), + ), + ); + } + } + for (const entry of await readdir(root, { + recursive: true, + withFileTypes: true, + })) { + if (!entry.isFile() || !/\.(js|ts)$/.test(entry.name)) continue; + const path = join(entry.parentPath, entry.name); + const contents = await readFile(path, "utf8"); + const rewritten = contents.replace( + /(["'])((?:@anatomy-cli\/(?:anatomy|schemas))(?:\/[^"']*)?)\1/g, + (_, quote: string, specifier: string) => { + const target = + mappings.get(specifier) ?? + (specifier.startsWith("@anatomy-cli/schemas/anatomy/") + ? join( + root, + "packages/schemas/src/anatomy", + specifier.slice("@anatomy-cli/schemas/anatomy/".length) + + ".js", + ) + : undefined); + if (!target) + throw new NpmReleaseError( + `Unresolved internal import in ${path}: ${specifier}`, + ); + const local = relative(dirname(path), target).replaceAll("\\", "/"); + return ( + quote + (local.startsWith(".") ? local : "./" + local) + quote + ); + }, + ); + if (rewritten !== contents) await writeFile(path, rewritten); + } + })(), + (cause) => + new NpmReleaseError( + `Package import resolution failed: ${cause instanceof Error ? cause.message : String(cause)}`, + ), + ); diff --git a/apps/anatomy-cli/src/runNpmRelease.ts b/apps/anatomy-cli/src/runNpmRelease.ts index 441698d..e8d6864 100644 --- a/apps/anatomy-cli/src/runNpmRelease.ts +++ b/apps/anatomy-cli/src/runNpmRelease.ts @@ -12,16 +12,8 @@ export const runNpmRelease = (mode: string) => (async () => { const root = resolve(import.meta.dirname, "../../.."); const output = join(root, "docs/verification/npm-release/artifacts"); - const packagePaths = [ - "packages/schemas", - "packages/anatomy", - "apps/anatomy-cli", - ]; - const names = [ - "@anatomy-cli/schemas", - "@anatomy-cli/anatomy", - "anatomy-cli", - ]; + const packagePaths = ["apps/anatomy-cli"]; + const names = ["anatomy-cli"]; const exec = async (command: string, args: string[], cwd = root) => ( await promisify(execFile)(command, args, { @@ -82,8 +74,8 @@ export const runNpmRelease = (mode: string) => ); await writeFile( join(consumer, "check.mjs"), - `import { scanAnatomy, queryAnatomyBundle } from '@anatomy-cli/anatomy'; -import { AnatomyScanOutcomeSchema } from '@anatomy-cli/schemas'; + `import { scanAnatomy, queryAnatomyBundle } from 'anatomy-cli'; +import { AnatomyScanOutcomeSchema } from 'anatomy-cli'; import {createRequire} from 'node:module'; import {readFileSync} from 'node:fs'; const require=createRequire(import.meta.url); @@ -113,7 +105,7 @@ console.log(JSON.stringify({node:process.version,version:${JSON.stringify(versio throw new NpmReleaseError("Installed CLI does not expose --bundle"); await writeFile( join(consumer, "check.ts"), - "import {scanAnatomy} from '@anatomy-cli/anatomy';\nimport type {AnatomyScanOutcome} from '@anatomy-cli/schemas';\nconst result: Promise = scanAnatomy({});\nvoid result;\n", + "import {scanAnatomy} from 'anatomy-cli';\nimport type {AnatomyScanOutcome} from 'anatomy-cli';\nconst result: Promise = scanAnatomy({});\nvoid result;\n", ); await exec( "node", @@ -155,15 +147,24 @@ console.log(JSON.stringify({node:process.version,version:${JSON.stringify(versio url: "git+https://github.com/forge-town/anatomy-cli.git", directory: path, }; + if (pkg.private || pkg.name !== "anatomy-cli") + throw new NpmReleaseError( + "Only the public anatomy-cli package may be published", + ); for (const key of [ "dependencies", - "devDependencies", "peerDependencies", "optionalDependencies", - ]) { - for (const name of Object.keys(pkg[key] ?? {})) - if (names.includes(name)) pkg[key][name] = plan.value.version; - } + ]) + if ( + Object.keys(pkg[key] ?? {}).some((name) => + name.startsWith("@anatomy-cli/"), + ) + ) + throw new NpmReleaseError( + "Public package cannot depend on private workspaces", + ); + delete pkg.devDependencies; const staging = join( output, "packages", @@ -320,7 +321,7 @@ console.log(JSON.stringify({node:process.version,version:${JSON.stringify(versio "registry-consumer", plan.version, ); - console.log(`Verified all packages at ${plan.version} (${plan.tag})`); + console.log(`Verified anatomy-cli at ${plan.version} (${plan.tag})`); })(), (cause) => cause instanceof NpmReleaseError diff --git a/apps/anatomy-cli/tsconfig.build.json b/apps/anatomy-cli/tsconfig.build.json index e01fb56..5af85bc 100644 --- a/apps/anatomy-cli/tsconfig.build.json +++ b/apps/anatomy-cli/tsconfig.build.json @@ -4,15 +4,21 @@ "noEmit": false, "declaration": true, "declarationMap": false, - "rootDir": "src", + "rootDir": "../..", "outDir": "dist", - "paths": {}, - "emitDeclarationOnly": true + "emitDeclarationOnly": false }, "include": [ "src" ], "exclude": [ - "src/**/*.spec.ts" + "src/**/*.spec.ts", + "../../packages/**/*.spec.ts", + "src/build-main.ts", + "src/resolvePackageImports.ts", + "src/release-main.ts", + "src/runNpmRelease.ts", + "src/planNpmRelease.ts", + "src/NpmReleaseError.ts" ] } diff --git a/bun.lock b/bun.lock index 2c9c3a2..f702413 100644 --- a/bun.lock +++ b/bun.lock @@ -24,9 +24,9 @@ "anatomy": "./bin/anatomy.js", }, "dependencies": { - "@anatomy-cli/anatomy": "^0.1.0", - "@anatomy-cli/schemas": "^0.1.0", "neverthrow": "^8.2.0", + "typescript": "5.9.2", + "zod": "^4.3.6", }, "devDependencies": { "@types/node": "^25.9.2", @@ -85,7 +85,7 @@ "name": "@anatomy-cli/anatomy", "version": "0.1.0", "dependencies": { - "@anatomy-cli/schemas": "^0.1.0", + "@anatomy-cli/schemas": "workspace:*", "neverthrow": "^8.2.0", "typescript": "5.9.2", }, diff --git a/packages/anatomy/package.json b/packages/anatomy/package.json index 3e909c4..9d8c552 100644 --- a/packages/anatomy/package.json +++ b/packages/anatomy/package.json @@ -31,7 +31,7 @@ "prepack": "bun run build" }, "dependencies": { - "@anatomy-cli/schemas": "^0.1.0", + "@anatomy-cli/schemas": "workspace:*", "neverthrow": "^8.2.0", "typescript": "5.9.2" }, @@ -45,10 +45,8 @@ "dist" ], "types": "./dist/index.d.ts", - "publishConfig": { - "access": "public" - }, "engines": { "node": ">=24" - } + }, + "private": true } diff --git a/packages/schemas/package.json b/packages/schemas/package.json index 800c319..833b2c1 100644 --- a/packages/schemas/package.json +++ b/packages/schemas/package.json @@ -44,10 +44,8 @@ "dist" ], "types": "./dist/index.d.ts", - "publishConfig": { - "access": "public" - }, "engines": { "node": ">=24" - } + }, + "private": true } From 47a17b2edea3dbb0aad8417125632e553a8345a3 Mon Sep 17 00:00:00 2001 From: Zander Zhang <276678881@qq.com> Date: Tue, 15 Sep 2026 18:15:08 +0800 Subject: [PATCH 7/8] fix: retain npm publication output for release diagnostics --- apps/anatomy-cli/src/runNpmRelease.ts | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/apps/anatomy-cli/src/runNpmRelease.ts b/apps/anatomy-cli/src/runNpmRelease.ts index e8d6864..950cdb2 100644 --- a/apps/anatomy-cli/src/runNpmRelease.ts +++ b/apps/anatomy-cli/src/runNpmRelease.ts @@ -14,13 +14,17 @@ export const runNpmRelease = (mode: string) => const output = join(root, "docs/verification/npm-release/artifacts"); const packagePaths = ["apps/anatomy-cli"]; const names = ["anatomy-cli"]; - const exec = async (command: string, args: string[], cwd = root) => - ( - await promisify(execFile)(command, args, { - cwd, - maxBuffer: 16 * 1024 * 1024, - }) - ).stdout.trim(); + const exec = async (command: string, args: string[], cwd = root) => { + const result = await promisify(execFile)(command, args, { + cwd, + maxBuffer: 16 * 1024 * 1024, + }); + if (command === "npm" && args[0] === "publish") { + console.log(result.stdout.trim()); + console.log(result.stderr.trim()); + } + return result.stdout.trim(); + }; const source = await exec("git", ["rev-parse", "HEAD"]); const manifest = async (path: string) => JSON.parse(await readFile(join(root, path, "package.json"), "utf8")); From 8b18b78dce32c7c7559809a11895395c7ed53151 Mon Sep 17 00:00:00 2001 From: Zander Zhang <276678881@qq.com> Date: Tue, 15 Sep 2026 18:22:06 +0800 Subject: [PATCH 8/8] fix: wait for asynchronous npm publication processing --- README.md | 3 ++- README.zh-CN.md | 2 +- apps/anatomy-cli/src/runNpmRelease.ts | 11 +++++++---- 3 files changed, 10 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 3be1e80..35bfec1 100644 --- a/README.md +++ b/README.md @@ -362,7 +362,8 @@ Configure the repository Actions secret `NPM_TOKEN` with non-interactive publish access to `anatomy-cli`. The workflow uses Node from `.nvmrc`, runs `bun run quality`, installs the packed CLI and SDK in an isolated consumer, then publishes with provenance. It reads back registry versions, integrity and tags, and installs the published package -again. Release plans, tarballs and consumer results are uploaded as run artifacts. +again. Registry verification waits up to 15 minutes for npm to finish processing a +publication. Release plans, tarballs and consumer results are uploaded as run artifacts. To publish a canary manually after the workflow reaches `main`: diff --git a/README.zh-CN.md b/README.zh-CN.md index 236cf4a..6a7e0e3 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -247,7 +247,7 @@ bun run build 先在仓库 Actions Secrets 配置 `NPM_TOKEN`,只需授予 `anatomy-cli` 的无交互发布权限。工作流使用 `.nvmrc` 中的 Node,运行 `bun run quality`, 独立安装打包后的 CLI 和 SDK 验证,再携带 provenance 发布。发布后回读 registry 的版本、 -完整性和标签,并重新安装验证。版本计划、tarball 和消费验证结果保存在 Actions artifacts。 +完整性和标签,并重新安装验证。npm 异步处理发布时,校验最多等待 15 分钟。版本计划、tarball 和消费验证结果保存在 Actions artifacts。 工作流进入 `main` 后,可以手动发布 canary: diff --git a/apps/anatomy-cli/src/runNpmRelease.ts b/apps/anatomy-cli/src/runNpmRelease.ts index 950cdb2..023c917 100644 --- a/apps/anatomy-cli/src/runNpmRelease.ts +++ b/apps/anatomy-cli/src/runNpmRelease.ts @@ -303,7 +303,7 @@ console.log(JSON.stringify({node:process.version,version:${JSON.stringify(versio } for (const pkg of plan.packages) { let confirmed = false; - for (let attempt = 0; attempt < 6; attempt++) { + for (let attempt = 0; attempt < 46; attempt++) { const history = await readHistory(pkg.name); const published = history.versions[plan.version]; confirmed = @@ -311,9 +311,12 @@ console.log(JSON.stringify({node:process.version,version:${JSON.stringify(versio published.dist?.integrity === pkg.integrity && history.tags[plan.tag] === plan.version; if (confirmed) break; - await new Promise((resolve) => - setTimeout(resolve, 1000 * 2 ** attempt), - ); + if (attempt < 45) { + console.log( + `Waiting for npm to process ${pkg.name}@${plan.version} (${attempt + 1}/45)`, + ); + await new Promise((resolve) => setTimeout(resolve, 20_000)); + } } if (!confirmed) throw new NpmReleaseError(