用于稳定描述代码结构的数据结构方案

  Entity {
    apiVersion: "backstage.io/v1alpha1"   // 版本化
    kind: "Component" | "API" | "Resource" | "System" | "Domain"  // 实体种类
    metadata: {
      name: "my-service"                  // 唯一标识
      namespace: "default"
      tags: ["java", "backend"]
      annotations: { ... }
    }
    spec: {
      type: "service"                     // 子类型
      owner: "team-a"                     // 归属
      lifecycle: "production"
      providesApis: ["my-api"]            // 暴露的接口
      consumesApis: ["other-api"]         // 消费的接口
      dependsOn: ["other-component"]      // 依赖
      partOf: ["my-system"]              // 层级归属
    }
  }

import { app, route, page, query, action, job } from "@wasp.sh/spec";
import { MainPage } from "./src/MainPage" with { type: "ref" };
import { getTasks } from "./src/queries" with { type: "ref" };
import { createTask } from "./src/actions" with { type: "ref" };

export default app({
  name: "TodoApp",
  title: "TodoApp",
  spec: [
    route("RootRoute", "/", page(MainPage)),
    query(getTasks, { entities: ["Task"] }),
    action(createTask, { entities: ["Task"] }),
  ],
})

import { defineCatalog } from '@json-render/core';
import { z } from 'zod';

export const catalog = defineCatalog(schema, {
  components: {
    Card: {
      props: z.object({
        title: z.string(),
        description: z.string().optional(),
      }),
      children: true,        // 可以有子元素
    },
    Button: {
      props: z.object({
        label: z.string(),
        variant: z.enum(['default', 'destructive', 'outline', 'ghost']),
      }),
      children: false,       // 无子元素
    },
  },
});

// 约束类型枚举
const ConditionSchema = z.discriminatedUnion("conditionType", [
  z.object({
    conditionType: z.literal("text"),
    value: z.string(),                         // 现有的文本约束
  }),
  z.object({
    conditionType: z.literal("archetype_ref"),
    archetypeId: z.string(),                   // 现有的 Archetype 引用
  }),
  z.object({
    conditionType: z.literal("path_pattern"),
    pattern: z.string(),                       // 文件路径必须匹配 glob
    modifier: z.enum(["must_exist", "must_not_exist", "must_contain"]),
  }),
  z.object({
    conditionType: z.literal("dependency"),
    direction: z.enum(["depends_on", "depended_on_by"]),
    targetPattern: z.string(),                 // 依赖目标匹配模式
    cardinality: z.enum(["at_least_one", "exactly_one", "zero_or_more"]).optional(),
  }),
  z.object({
    conditionType: z.literal("structural"),
    constraint: z.enum([
      "has_readme", "has_tests", "has_stories",
      "has_index_barrel", "no_circular_deps",
      "single_responsibility", "public_api_documented",
    ]),
  }),
  z.object({
    conditionType: z.literal("quantity"),
    target: z.string(),                        // 目标元素（如 "files", "exports", "dependencies"）
    operator: z.enum(["eq", "gt", "gte", "lt", "lte", "between"]),
    value: z.number(),
    maxValue: z.number().optional(),           // between 时用
  }),
]);

// === 1. StructureUnit：统一结构单元（泛化 Crate、Archetype、Repository 等）===

interface StructureUnit {
  /** 全局唯一标识，格式: {kind}:{namespace}/{name} */
  uid: string;

  /** 结构单元种类 */
  kind: StructureKind; // "crate" | "archetype" | "repository" | "page" | "service" | custom

  /** 结构单元子类型（可多值，可扩展） */
  types: string[]; // 替代当前 Crate.type 固定枚举

  /** 人类可读名称 */
  displayName: string;

  /** 描述 */
  description?: string;

  /** 所属父结构单元（层级关系） */
  parentUid?: string;

  /** 所处层级 */
  level?: StructureLevel; // "workspace" | "repository" | "crate" | "module" | "file" | "function"

  /** 边界定义 */
  boundary?: Boundary;

  /** 扩展属性 */
  properties?: Record<string, unknown>;
}

type StructureKind = string; // 可扩展：不仅是内置 kind，用户可定义新 kind
type StructureLevel = string; // 可扩展

// === 2. Boundary：边界定义 ===

interface Boundary {
  /** 暴露的接口——对外可见的 API */
  exposes: ExposedInterface[];
  /** 内部实现范围（文件路径 glob 模式） */
  encapsulations: string[];
  /** 可见性控制 */
  visibility: "public" | "internal" | "private";
}

interface ExposedInterface {
  name: string;
  kind: "function" | "class" | "type" | "variable" | "component" | "route" | custom;
  signature?: string;
  path: string; // 文件路径
}

// === 3. Relation：结构单元之间的关系（一等公民）===

interface Relation {
  /** 关系 ID */
  id: string;
  /** 源结构单元 uid */
  sourceUid: string;
  /** 目标结构单元 uid */
  targetUid: string;
  /** 关系类型 */
  relationType: RelationType;
  /** 关系属性 */
  properties?: RelationProperties;
}

type RelationType =
  | "dependsOn"       // 运行时依赖
  | "partOf"          // 作为目标的一部分
  | "hasPart"          // 包含子单元
  | "implements"       // 实现了目标的接口/契约
  | "references"       // 引用（非依赖的弱引用）
  | "conformsTo";      // 符合 Archetype（Crate → Archetype 的关系）

interface RelationProperties {
  strength?: "strong" | "weak";
  direction?: "unidirectional" | "bidirectional";
  reason?: string;
  [key: string]: unknown; // 可扩展
}

// === 4. Constraint：约束（升级后的 Condition）===

type Constraint =
  | TextConstraint
  | ArchetypeRefConstraint
  | PathPatternConstraint
  | DependencyConstraint
  | StructuralConstraint
  | QuantityConstraint;

interface TextConstraint {
  constraintType: "text";
  value: string;
}

interface ArchetypeRefConstraint {
  constraintType: "archetype_ref";
  archetypeUid: string;
}

interface PathPatternConstraint {
  constraintType: "path_pattern";
  pattern: string;           // glob
  modifier: "must_exist" | "must_not_exist" | "must_contain";
}

interface DependencyConstraint {
  constraintType: "dependency";
  direction: "depends_on" | "depended_on_by";
  targetPattern: string;
  cardinality?: "at_least_one" | "exactly_one" | "zero_or_more";
}

interface StructuralConstraint {
  constraintType: "structural";
  rule: string; // "has_readme" | "has_tests" | "has_stories" | "has_index_barrel" | "no_circular_deps" | custom
}

interface QuantityConstraint {
  constraintType: "quantity";
  target: string;     // "files" | "exports" | "dependencies" | ...
  operator: "eq" | "gt" | "gte" | "lt" | "lte" | "between";
  value: number;
  maxValue?: number;
}

const buttonCrate: StructureUnit = {
  uid: "crate:default/ui-button",
  kind: "crate",
  types: ["component", "ui"],
  displayName: "Button",
  description: "基础交互触发组件",
  level: "crate",
  boundary: {
    exposes: [
      { name: "Button", kind: "component", path: "src/components/Button/Button.tsx" },
    ],
    encapsulations: ["src/components/Button/**"],
    visibility: "public",
  },
};

const buttonArchetype: StructureUnit = {
  uid: "archetype:default/component-design-best-practice",
  kind: "archetype",
  types: ["design-contract"],
  displayName: "Component Design Best Practice",
  level: "crate",
};

const conformsRelation: Relation = {
  id: "rel-001",
  sourceUid: "crate:default/ui-button",
  targetUid: "archetype:default/component-design-best-practice",
  relationType: "conformsTo",
  properties: { strength: "strong" },
};

const buttonGroupCrate: StructureUnit = {
  uid: "crate:default/ui-button-group",
  kind: "crate",
  types: ["component", "container"],
  displayName: "ButtonGroup",
  level: "crate",
};

const compositionRelation: Relation = {
  id: "rel-002",
  sourceUid: "crate:default/ui-button-group",
  targetUid: "crate:default/ui-button",
  relationType: "dependsOn",
  properties: { strength: "strong", reason: "ButtonGroup 聚合 Button 实例" },
};

const daedalusRepo: StructureUnit = {
  uid: "repository:default/daedalus",
  kind: "repository",
  types: ["monorepo", "turborepo"],
  displayName: "Daedalus",
  level: "repository",
};

const appPackage: StructureUnit = {
  uid: "crate:default/daedalus-app",
  kind: "crate",
  types: ["application", "web"],
  displayName: "@daedalus/app",
  level: "crate",
  parentUid: "repository:default/daedalus", // 层级关系
};

const appToAppRelation: Relation = {
  id: "rel-003",
  sourceUid: "crate:default/daedalus-app",
  targetUid: "repository:default/daedalus",
  relationType: "partOf", // 与 parentUid 呼应但更语义化
};