@documentation-robotics/cli 0.2.0 → 0.4.0

package/dist/core/annotation-store.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/core/annotation-store.ts"],
-  "sourcesContent": ["/**\n * AnnotationStore - filesystem-backed storage for element annotations.\n *\n * Persists annotations under documentation-robotics/annotations/{id}.yaml, one\n * file per annotation with its replies embedded. This is what gives the MCP\n * annotation_* tools (a separate stdio process per session, with no shared\n * memory with a running `dr server`) the same annotation capabilities as the\n * REST server's in-memory /api/annotations endpoints, backed by durable\n * storage that survives process restarts.\n */\n\nimport { readFile, readdir, rm } from \"fs/promises\";\nimport { randomBytes } from \"crypto\";\nimport path from \"path\";\nimport yaml from \"yaml\";\nimport { z } from \"zod\";\nimport { atomicWrite, ensureDir, fileExists } from \"../utils/file-io.js\";\nimport { FileLock } from \"../utils/file-lock.js\";\nimport { getErrorMessage } from \"../utils/errors.js\";\n\nconst AnnotationReplySchema = z.object({\n  id: z.string(),\n  author: z.string(),\n  content: z.string(),\n  createdAt: z.string(),\n});\n\n/**\n * Runtime schema for an annotation file on disk, used to validate parsed YAML\n * before it is trusted as an `Annotation` \u2014 hand-edited files can otherwise\n * omit required fields (e.g. `tags`) and crash downstream consumers.\n */\nconst AnnotationSchema = z.object({\n  id: z.string(),\n  elementId: z.string(),\n  author: z.string(),\n  content: z.string(),\n  createdAt: z.string(),\n  updatedAt: z.string().optional(),\n  tags: z.array(z.string()),\n  resolved: z.boolean(),\n  replies: z.array(AnnotationReplySchema),\n});\n\nexport type AnnotationReply = z.infer<typeof AnnotationReplySchema>;\n\nexport type Annotation = z.infer<typeof AnnotationSchema>;\n\nexport interface AnnotationCreateInput {\n  elementId: string;\n  author?: string;\n  content: string;\n  tags?: string[];\n}\n\nexport interface AnnotationUpdateInput {\n  content?: string;\n  tags?: string[];\n  resolved?: boolean;\n}\n\nexport interface AnnotationReplyCreateInput {\n  author: string;\n  content: string;\n}\n\nexport class AnnotationStore {\n  private annotationsDir: string;\n\n  constructor(rootPath: string) {\n    this.annotationsDir = path.join(rootPath, \"documentation-robotics\", \"annotations\");\n  }\n\n  /** Lists all annotations, optionally filtered to a single element, oldest first. Skips (and warns on) individual files that fail to load rather than failing the whole list. */\n  async list(elementId?: string): Promise<Annotation[]> {\n    if (!(await fileExists(this.annotationsDir))) {\n      return [];\n    }\n\n    const entries = await readdir(this.annotationsDir, { withFileTypes: true });\n    const annotations: Annotation[] = [];\n\n    for (const entry of entries) {\n      if (!entry.isFile() || !entry.name.endsWith(\".yaml\")) continue;\n      const id = entry.name.slice(0, -\".yaml\".length);\n\n      let annotation: Annotation | null;\n      try {\n        annotation = await this.get(id);\n      } catch (error) {\n        process.stderr.write(`Warning: Skipping annotation '${id}': ${getErrorMessage(error)}\\n`);\n        continue;\n      }\n\n      if (annotation && (!elementId || annotation.elementId === elementId)) {\n        annotations.push(annotation);\n      }\n    }\n\n    return annotations.sort((a, b) => a.createdAt.localeCompare(b.createdAt));\n  }\n\n  async get(id: string): Promise<Annotation | null> {\n    const filePath = this.getPath(id);\n    if (!(await fileExists(filePath))) {\n      return null;\n    }\n\n    let parsed: unknown;\n    try {\n      const content = await readFile(filePath, \"utf-8\");\n      parsed = yaml.parse(content);\n    } catch (error) {\n      throw new Error(`Failed to load annotation '${id}': ${getErrorMessage(error)}`);\n    }\n\n    const result = AnnotationSchema.safeParse(parsed);\n    if (!result.success) {\n      throw new Error(\n        `Failed to load annotation '${id}': invalid annotation data - ${result.error.message}`\n      );\n    }\n    return result.data;\n  }\n\n  async create(input: AnnotationCreateInput): Promise<Annotation> {\n    const annotation: Annotation = {\n      id: this.generateAnnotationId(),\n      elementId: input.elementId,\n      author: input.author?.trim() || \"Anonymous\",\n      content: input.content,\n      createdAt: new Date().toISOString(),\n      tags: input.tags ?? [],\n      resolved: false,\n      replies: [],\n    };\n\n    await ensureDir(this.annotationsDir);\n    await atomicWrite(this.getPath(annotation.id), yaml.stringify(annotation));\n    return annotation;\n  }\n\n  /** Partially updates an annotation's content, tags, and/or resolved state. Returns null if not found. */\n  async update(id: string, updates: AnnotationUpdateInput): Promise<Annotation | null> {\n    const filePath = this.getPath(id);\n    await ensureDir(this.annotationsDir);\n    const lock = new FileLock(filePath);\n\n    return lock.withLock(async () => {\n      const annotation = await this.get(id);\n      if (!annotation) return null;\n\n      const updated: Annotation = {\n        ...annotation,\n        content: updates.content ?? annotation.content,\n        tags: updates.tags ?? annotation.tags,\n        resolved: updates.resolved ?? annotation.resolved,\n        updatedAt: new Date().toISOString(),\n      };\n\n      await atomicWrite(filePath, yaml.stringify(updated));\n      return updated;\n    });\n  }\n\n  /** Deletes an annotation and its replies. Returns false if it didn't exist. */\n  async delete(id: string): Promise<boolean> {\n    const filePath = this.getPath(id);\n    if (!(await fileExists(filePath))) {\n      return false;\n    }\n    await rm(filePath, { force: true });\n    return true;\n  }\n\n  /** Appends a reply to an annotation. Returns null if the annotation doesn't exist. */\n  async addReply(id: string, input: AnnotationReplyCreateInput): Promise<AnnotationReply | null> {\n    const filePath = this.getPath(id);\n    await ensureDir(this.annotationsDir);\n    const lock = new FileLock(filePath);\n\n    return lock.withLock(async () => {\n      const annotation = await this.get(id);\n      if (!annotation) return null;\n\n      const reply: AnnotationReply = {\n        id: this.generateReplyId(),\n        author: input.author,\n        content: input.content,\n        createdAt: new Date().toISOString(),\n      };\n\n      annotation.replies.push(reply);\n      await atomicWrite(filePath, yaml.stringify(annotation));\n      return reply;\n    });\n  }\n\n  private getPath(id: string): string {\n    return path.join(this.annotationsDir, `${this.sanitizeId(id)}.yaml`);\n  }\n\n  /** Whitelists safe characters so an annotation ID can't escape annotationsDir via path traversal. */\n  private sanitizeId(id: string): string {\n    const sanitized = id.replace(/[^a-zA-Z0-9_-]/g, \"\");\n    if (!sanitized) {\n      throw new Error(`Invalid annotation ID '${id}'`);\n    }\n    return sanitized;\n  }\n\n  private generateAnnotationId(): string {\n    return `ann-${Date.now()}-${randomBytes(4).toString(\"hex\")}`;\n  }\n\n  private generateReplyId(): string {\n    return `reply-${Date.now()}-${randomBytes(4).toString(\"hex\")}`;\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["/**\n * AnnotationStore - filesystem-backed storage for element annotations.\n *\n * Persists annotations under documentation-robotics/annotations/{id}.yaml, one\n * file per annotation with its replies embedded. It is the one annotation store:\n * the viewer server's /api/annotations routes and the MCP annotation_* tools (a\n * separate process per session) both read and write it, so each sees the other's\n * annotations and replies, and they survive restarts. The viewer server watches\n * the directory and broadcasts changes other processes make.\n */\n\nimport { readFile, readdir, rm } from \"fs/promises\";\nimport { randomBytes } from \"crypto\";\nimport path from \"path\";\nimport yaml from \"yaml\";\nimport { z } from \"zod\";\nimport { atomicWrite, ensureDir, fileExists } from \"../utils/file-io.js\";\nimport { FileLock } from \"../utils/file-lock.js\";\nimport { getErrorMessage } from \"../utils/errors.js\";\n\nconst AnnotationReplySchema = z.object({\n  id: z.string(),\n  author: z.string(),\n  content: z.string(),\n  createdAt: z.string(),\n});\n\n/**\n * Runtime schema for an annotation file on disk, used to validate parsed YAML\n * before it is trusted as an `Annotation` \u2014 hand-edited files can otherwise\n * omit required fields (e.g. `tags`) and crash downstream consumers.\n */\nconst AnnotationSchema = z.object({\n  id: z.string(),\n  elementId: z.string(),\n  author: z.string(),\n  content: z.string(),\n  createdAt: z.string(),\n  updatedAt: z.string().optional(),\n  tags: z.array(z.string()),\n  resolved: z.boolean(),\n  replies: z.array(AnnotationReplySchema),\n});\n\nexport type AnnotationReply = z.infer<typeof AnnotationReplySchema>;\n\nexport type Annotation = z.infer<typeof AnnotationSchema>;\n\nexport interface AnnotationCreateInput {\n  elementId: string;\n  author?: string;\n  content: string;\n  tags?: string[];\n}\n\nexport interface AnnotationUpdateInput {\n  content?: string;\n  tags?: string[];\n  resolved?: boolean;\n}\n\nexport interface AnnotationReplyCreateInput {\n  author: string;\n  content: string;\n}\n\nlet lastCreatedAt = 0;\n\n/**\n * A creation time that never repeats within this process. Annotations list oldest first by\n * createdAt, so two made in the same millisecond (a viewer comment and its follow-up, say) would\n * otherwise come back in directory order.\n */\nfunction nextCreatedAt(): string {\n  lastCreatedAt = Math.max(Date.now(), lastCreatedAt + 1);\n  return new Date(lastCreatedAt).toISOString();\n}\n\n/** Now, or the given time if the clock is behind it (nextCreatedAt can run ahead in a burst). */\nfunction notBefore(iso: string): string {\n  return new Date(Math.max(Date.now(), Date.parse(iso) || 0)).toISOString();\n}\n\nexport class AnnotationStore {\n  private annotationsDir: string;\n\n  constructor(rootPath: string) {\n    this.annotationsDir = path.join(rootPath, \"documentation-robotics\", \"annotations\");\n  }\n\n  /** Lists all annotations, optionally filtered to a single element, oldest first. Skips (and warns on) individual files that fail to load rather than failing the whole list. */\n  async list(elementId?: string): Promise<Annotation[]> {\n    if (!(await fileExists(this.annotationsDir))) {\n      return [];\n    }\n\n    const entries = await readdir(this.annotationsDir, { withFileTypes: true });\n    const annotations: Annotation[] = [];\n\n    for (const entry of entries) {\n      if (!entry.isFile() || !entry.name.endsWith(\".yaml\")) continue;\n      const id = entry.name.slice(0, -\".yaml\".length);\n\n      let annotation: Annotation | null;\n      try {\n        annotation = await this.get(id);\n      } catch (error) {\n        process.stderr.write(`Warning: Skipping annotation '${id}': ${getErrorMessage(error)}\\n`);\n        continue;\n      }\n\n      if (annotation && (!elementId || annotation.elementId === elementId)) {\n        annotations.push(annotation);\n      }\n    }\n\n    return annotations.sort((a, b) => a.createdAt.localeCompare(b.createdAt));\n  }\n\n  async get(id: string): Promise<Annotation | null> {\n    const filePath = this.getPath(id);\n    if (!(await fileExists(filePath))) {\n      return null;\n    }\n\n    let parsed: unknown;\n    try {\n      const content = await readFile(filePath, \"utf-8\");\n      parsed = yaml.parse(content);\n    } catch (error) {\n      throw new Error(`Failed to load annotation '${id}': ${getErrorMessage(error)}`);\n    }\n\n    const result = AnnotationSchema.safeParse(parsed);\n    if (!result.success) {\n      throw new Error(\n        `Failed to load annotation '${id}': invalid annotation data - ${result.error.message}`\n      );\n    }\n    return result.data;\n  }\n\n  async create(input: AnnotationCreateInput): Promise<Annotation> {\n    const annotation: Annotation = {\n      id: this.generateAnnotationId(),\n      elementId: input.elementId,\n      author: input.author?.trim() || \"Anonymous\",\n      content: input.content,\n      createdAt: nextCreatedAt(),\n      tags: input.tags ?? [],\n      resolved: false,\n      replies: [],\n    };\n\n    await ensureDir(this.annotationsDir);\n    await atomicWrite(this.getPath(annotation.id), yaml.stringify(annotation));\n    return annotation;\n  }\n\n  /** Partially updates an annotation's content, tags, and/or resolved state. Returns null if not found. */\n  async update(id: string, updates: AnnotationUpdateInput): Promise<Annotation | null> {\n    const filePath = this.getPath(id);\n    await ensureDir(this.annotationsDir);\n    const lock = new FileLock(filePath);\n\n    return lock.withLock(async () => {\n      const annotation = await this.get(id);\n      if (!annotation) return null;\n\n      const updated: Annotation = {\n        ...annotation,\n        content: updates.content ?? annotation.content,\n        tags: updates.tags ?? annotation.tags,\n        resolved: updates.resolved ?? annotation.resolved,\n        updatedAt: notBefore(annotation.createdAt),\n      };\n\n      await atomicWrite(filePath, yaml.stringify(updated));\n      return updated;\n    });\n  }\n\n  /**\n   * Deletes an annotation and its replies. Returns false if it didn't exist. Holds the same lock\n   * as update and addReply, so a write in flight can't bring the annotation back.\n   */\n  async delete(id: string): Promise<boolean> {\n    const filePath = this.getPath(id);\n    if (!(await fileExists(filePath))) {\n      return false;\n    }\n    const lock = new FileLock(filePath);\n    return lock.withLock(async () => {\n      if (!(await fileExists(filePath))) return false;\n      await rm(filePath, { force: true });\n      return true;\n    });\n  }\n\n  /** Appends a reply to an annotation. Returns null if the annotation doesn't exist. */\n  async addReply(id: string, input: AnnotationReplyCreateInput): Promise<AnnotationReply | null> {\n    const filePath = this.getPath(id);\n    await ensureDir(this.annotationsDir);\n    const lock = new FileLock(filePath);\n\n    return lock.withLock(async () => {\n      const annotation = await this.get(id);\n      if (!annotation) return null;\n\n      const reply: AnnotationReply = {\n        id: this.generateReplyId(),\n        author: input.author,\n        content: input.content,\n        createdAt: notBefore(annotation.createdAt),\n      };\n\n      annotation.replies.push(reply);\n      await atomicWrite(filePath, yaml.stringify(annotation));\n      return reply;\n    });\n  }\n\n  private getPath(id: string): string {\n    return path.join(this.annotationsDir, `${this.sanitizeId(id)}.yaml`);\n  }\n\n  /** Whitelists safe characters so an annotation ID can't escape annotationsDir via path traversal. */\n  private sanitizeId(id: string): string {\n    const sanitized = id.replace(/[^a-zA-Z0-9_-]/g, \"\");\n    if (!sanitized) {\n      throw new Error(`Invalid annotation ID '${id}'`);\n    }\n    return sanitized;\n  }\n\n  private generateAnnotationId(): string {\n    return `ann-${Date.now()}-${randomBytes(4).toString(\"hex\")}`;\n  }\n\n  private generateReplyId(): string {\n    return `reply-${Date.now()}-${randomBytes(4).toString(\"hex\")}`;\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/core/catalog-migration.js

@@ -0,0 +1,34 @@
+import { migrateElementTypes, summarizeElementTypeChanges } from "./element-type-migration.js";
+import { migrateRelationshipsFile, migrateStagedChangesets, summarizeRelationshipChanges } from "./relationship-migration.js";
+async function applyCatalogMigrations(model, options = {}) {
+  const dryRun = options.dryRun ?? !1, types = await migrateElementTypes(model, void 0, { dryRun }), relationships = types.errors.length ? { filesModified: 0, changes: [], committed: { before: [], after: [] }, error: void 0 } : await migrateRelationshipsFile(model, void 0, { dryRun }), staged = relationships.error ? { changesetsModified: 0, changes: [], errors: [] } : await migrateStagedChangesets(model, relationships.committed, void 0, { dryRun }), summaries = [
+    ...types.changes.length > 0 ? [`element types renamed: ${summarizeElementTypeChanges(types.changes)}`] : [],
+    relationships.changes.length > 0 ? summarizeRelationshipChanges(relationships.changes) : "no relationships to rewrite",
+    ...staged.changes.length > 0 ? [summarizeRelationshipChanges(staged.changes, "staged relationship changes")] : []
+  ];
+  return {
+    filesModified: types.filesModified + types.changesetsModified + relationships.filesModified + staged.changesetsModified,
+    summaries,
+    errors: [...types.errors, ...relationships.error ? [relationships.error] : [], ...staged.errors],
+    details: {
+      elementTypeChanges: types.changes,
+      relationshipChanges: relationships.changes,
+      stagedRelationshipChanges: staged.changes,
+      ...!types.errors.length && !relationships.error ? { committedRelationshipsAfter: relationships.committed.after } : {}
+    }
+  };
+}
+async function pendingCatalogMigrations(model) {
+  const r = await applyCatalogMigrations(model, { dryRun: !0 });
+  return {
+    elementTypes: r.details.elementTypeChanges.length,
+    relationships: r.details.relationshipChanges.length,
+    stagedRelationships: r.details.stagedRelationshipChanges.length,
+    errors: r.errors
+  };
+}
+export {
+  applyCatalogMigrations,
+  pendingCatalogMigrations
+};
+//# sourceMappingURL=catalog-migration.js.map

package/dist/core/catalog-migration.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/core/catalog-migration.ts"],
+  "sourcesContent": ["/**\n * Catalog migration: brings a model's elements and relationships in line with the current spec\n * catalog, using the generated rewrite table (relationship-migration-table.ts).\n *\n *   1. element type renames (element-type-migration.ts), so the rules below see the new types\n *   2. relationship rewrites in relationships.yaml (relationship-migration.ts)\n *   3. the same rewrites in staged changesets\n *\n * It runs inside the 0.9.0 -> 0.10.0 and 0.10.0 -> 0.11.0 migrations, and on its own when `dr upgrade` finds a model\n * already at the current spec version that still names retired types or relationships: the\n * catalog can change between spec version bumps, and a model stamped with the version before\n * a change would otherwise never receive it. Every step only rewrites what the table matches,\n * so running it again on a migrated model changes nothing.\n */\nimport type { Model } from \"./model.js\";\nimport type { Relationship } from \"./relationships.js\";\nimport { migrateElementTypes, summarizeElementTypeChanges, type ElementTypeRenameChange } from \"./element-type-migration.js\";\nimport {\n  migrateRelationshipsFile,\n  migrateStagedChangesets,\n  summarizeRelationshipChanges,\n  type RelationshipRewriteChange,\n  type StagedRelationshipRewriteChange,\n} from \"./relationship-migration.js\";\n\nexport interface CatalogMigrationResult {\n  filesModified: number;\n  /** One phrase per kind of change, for the migration description */\n  summaries: string[];\n  errors: string[];\n  details: {\n    elementTypeChanges: ElementTypeRenameChange[];\n    relationshipChanges: RelationshipRewriteChange[];\n    stagedRelationshipChanges: StagedRelationshipRewriteChange[];\n    /**\n     * relationships.yaml as the migration leaves it (as it would, in a dry run). Absent when the\n     * relationships were not migrated (an element-type error, an unreadable file).\n     */\n    committedRelationshipsAfter?: Relationship[];\n  };\n}\n\nexport async function applyCatalogMigrations(\n  model: Model,\n  options: { dryRun?: boolean } = {}\n): Promise<CatalogMigrationResult> {\n  const dryRun = options.dryRun ?? false;\n  // Renamed element types first (product.capability -> product.softwarecapability), so the\n  // relationship rules, which name the new types, resolve the renamed elements.\n  const types = await migrateElementTypes(model, undefined, { dryRun });\n\n  const relationships = types.errors.length\n    ? { filesModified: 0, changes: [], committed: { before: [], after: [] }, error: undefined }\n    : await migrateRelationshipsFile(model, undefined, { dryRun });\n  const staged = relationships.error\n    ? { changesetsModified: 0, changes: [], errors: [] }\n    : await migrateStagedChangesets(model, relationships.committed, undefined, { dryRun });\n\n  const summaries = [\n    ...(types.changes.length > 0 ? [`element types renamed: ${summarizeElementTypeChanges(types.changes)}`] : []),\n    relationships.changes.length > 0 ? summarizeRelationshipChanges(relationships.changes) : \"no relationships to rewrite\",\n    ...(staged.changes.length > 0 ? [summarizeRelationshipChanges(staged.changes, \"staged relationship changes\")] : []),\n  ];\n\n  return {\n    filesModified: types.filesModified + types.changesetsModified + relationships.filesModified + staged.changesetsModified,\n    summaries,\n    errors: [...types.errors, ...(relationships.error ? [relationships.error] : []), ...staged.errors],\n    details: {\n      elementTypeChanges: types.changes,\n      relationshipChanges: relationships.changes,\n      stagedRelationshipChanges: staged.changes,\n      ...(!types.errors.length && !relationships.error ? { committedRelationshipsAfter: relationships.committed.after } : {}),\n    },\n  };\n}\n\n/** How many catalog changes the model still needs; all zero when it is in line with the catalog */\nexport async function pendingCatalogMigrations(\n  model: Model\n): Promise<{ elementTypes: number; relationships: number; stagedRelationships: number; errors: string[] }> {\n  const r = await applyCatalogMigrations(model, { dryRun: true });\n  return {\n    elementTypes: r.details.elementTypeChanges.length,\n    relationships: r.details.relationshipChanges.length,\n    stagedRelationships: r.details.stagedRelationshipChanges.length,\n    errors: r.errors,\n  };\n}\n"],
+  "mappings": "AAgBA,SAAS,qBAAqB,mCAAiE;AAC/F,SACE,0BACA,yBACA,oCAGK;AAmBP,eAAsB,uBACpB,OACA,UAAgC,CAAA,GAAE;AAElC,QAAM,SAAS,QAAQ,UAAU,IAG3B,QAAQ,MAAM,oBAAoB,OAAO,QAAW,EAAE,OAAM,CAAE,GAE9D,gBAAgB,MAAM,OAAO,SAC/B,EAAE,eAAe,GAAG,SAAS,CAAA,GAAI,WAAW,EAAE,QAAQ,CAAA,GAAI,OAAO,CAAA,EAAE,GAAI,OAAO,OAAS,IACvF,MAAM,yBAAyB,OAAO,QAAW,EAAE,OAAM,CAAE,GACzD,SAAS,cAAc,QACzB,EAAE,oBAAoB,GAAG,SAAS,CAAA,GAAI,QAAQ,CAAA,EAAE,IAChD,MAAM,wBAAwB,OAAO,cAAc,WAAW,QAAW,EAAE,OAAM,CAAE,GAEjF,YAAY;IAChB,GAAI,MAAM,QAAQ,SAAS,IAAI,CAAC,0BAA0B,4BAA4B,MAAM,OAAO,CAAC,EAAE,IAAI,CAAA;IAC1G,cAAc,QAAQ,SAAS,IAAI,6BAA6B,cAAc,OAAO,IAAI;IACzF,GAAI,OAAO,QAAQ,SAAS,IAAI,CAAC,6BAA6B,OAAO,SAAS,6BAA6B,CAAC,IAAI,CAAA;;AAGlH,SAAO;IACL,eAAe,MAAM,gBAAgB,MAAM,qBAAqB,cAAc,gBAAgB,OAAO;IACrG;IACA,QAAQ,CAAC,GAAG,MAAM,QAAQ,GAAI,cAAc,QAAQ,CAAC,cAAc,KAAK,IAAI,CAAA,GAAK,GAAG,OAAO,MAAM;IACjG,SAAS;MACP,oBAAoB,MAAM;MAC1B,qBAAqB,cAAc;MACnC,2BAA2B,OAAO;MAClC,GAAI,CAAC,MAAM,OAAO,UAAU,CAAC,cAAc,QAAQ,EAAE,6BAA6B,cAAc,UAAU,MAAK,IAAK,CAAA;;;AAG1H;AAGA,eAAsB,yBACpB,OAAY;AAEZ,QAAM,IAAI,MAAM,uBAAuB,OAAO,EAAE,QAAQ,GAAI,CAAE;AAC9D,SAAO;IACL,cAAc,EAAE,QAAQ,mBAAmB;IAC3C,eAAe,EAAE,QAAQ,oBAAoB;IAC7C,qBAAqB,EAAE,QAAQ,0BAA0B;IACzD,QAAQ,EAAE;;AAEd;",
+  "names": []
+}

package/dist/core/changeset-analysis.js

@@ -0,0 +1,421 @@
+import { getAllLayerIds } from "../generated/layer-registry.js";
+import { normalizeNodeType } from "../generated/node-types.js";
+import { getValidRelationships, RELATIONSHIPS_BY_DESTINATION, RELATIONSHIPS_BY_SOURCE } from "../generated/relationship-index.js";
+import { changesetRevisionToken } from "./changeset-graph.js";
+const INTENT_LAYERS = /* @__PURE__ */ new Set(["motivation", "business", "product"]), INTENT_TRACE_DEPTH = 4, DEFAULT_HUB_THRESHOLD = 15;
+function computeImpact(graph, options = {}) {
+  const depth = options.depth ?? 2, maxElements = options.maxElements ?? 200, hubThreshold = options.hubThreshold ?? DEFAULT_HUB_THRESHOLD, expandHubs = options.expandHubs ?? !1, changed = new Set(graph.changedElements().map((e) => e.id));
+  let start, unknownFrom;
+  if (options.from) {
+    start = /* @__PURE__ */ new Set(), unknownFrom = [];
+    for (const id of options.from) {
+      const element = graph.getElement(id);
+      element ? start.add(element.id) : unknownFrom.push(id);
+    }
+  } else
+    start = changed;
+  const reached = /* @__PURE__ */ new Map(), visited = new Set(start), hubs = [], perHop = /* @__PURE__ */ new Map();
+  let truncated = !1;
+  const reach = (from, neighbor, distance) => {
+    if (visited.has(neighbor.other))
+      return !1;
+    const element = graph.getElement(neighbor.other);
+    if (!element || element.status === "deleted")
+      return !1;
+    if (visited.add(neighbor.other), reached.size >= maxElements)
+      return truncated = !0, !1;
+    reached.set(element.id, {
+      id: element.id,
+      layer: element.layer,
+      name: element.name,
+      type: element.type,
+      distance,
+      via: describeHop(from, neighbor),
+      files: sourceFiles(element),
+      ...element.status === "added" || element.status === "updated" ? { status: element.status } : {}
+    }), perHop.set(distance, (perHop.get(distance) ?? 0) + 1);
+    const degree = graph.neighbors(element.id).length;
+    return !(degree > hubThreshold && (hubs.push({ id: element.id, degree, depth: distance }), !expandHubs));
+  };
+  let frontier = [];
+  if (!options.from)
+    for (const rel of graph.changedRelationships()) {
+      if (changed.has(rel.source) || changed.has(rel.target))
+        continue;
+      const asNeighbor = (other, direction) => ({ relationship: rel, direction, other });
+      reach(rel.source, asNeighbor(rel.target, "out"), 1) && frontier.push(rel.target), reach(rel.target, asNeighbor(rel.source, "in"), 1) && frontier.push(rel.source);
+    }
+  let current = [...start];
+  for (let distance = 1; distance <= depth && current.length + frontier.length > 0 && !truncated; distance++) {
+    const next = [];
+    for (const id of current) {
+      for (const neighbor of graph.neighbors(id, { includeDeleted: changed.has(id) }))
+        if (reach(id, neighbor, distance) && next.push(neighbor.other), truncated)
+          break;
+      if (truncated)
+        break;
+    }
+    current = [...frontier, ...next], frontier = [];
+  }
+  const byLayer = {};
+  for (const layer of orderedLayers([...reached.values()].map((e) => e.layer)))
+    byLayer[layer] = [...reached.values()].filter((e) => e.layer === layer).sort((a, b) => a.distance - b.distance || a.id.localeCompare(b.id)).map(({ layer: _layer, ...rest }) => rest);
+  return {
+    depth,
+    changed: changed.size,
+    reached: reached.size,
+    truncated,
+    byLayer,
+    perHop: [...perHop.entries()].sort(([a], [b]) => a - b).map(([d, n]) => ({ depth: d, reached: n })),
+    hubs: hubs.sort((a, b) => a.depth - b.depth || b.degree - a.degree || a.id.localeCompare(b.id)),
+    hubThreshold,
+    ...options.from ? { from: [...start], unknownFrom: unknownFrom ?? [] } : {},
+    ...options.from && start.size === 0 ? {
+      warnings: [
+        options.from.length === 0 ? "from is empty, so the walk had no start element and reached nothing; omit from to walk from every changed element." : "None of the from ids is in the projected model, so the walk had no start element and reached nothing; see unknownFrom."
+      ]
+    } : {}
+  };
+}
+function buildBrief({ graph, annotations = [], drift, unwired: unwiredMode = "summary", unwiredLayers, hubThreshold = DEFAULT_HUB_THRESHOLD }) {
+  const changeset = graph.changeset, changed = graph.changedElements(), changedIds = new Set(changed.map((e) => e.id)), changedRels = graph.changedRelationships(), inBase = graph.alreadyInBase(), layers = [];
+  for (const layer of orderedLayers(changed.map((e) => e.layer)))
+    layers.push({
+      layer,
+      changes: changed.filter((e) => e.layer === layer).map((e) => describeChange(graph, e))
+    });
+  const relationshipChanges = changedRels.filter((rel) => !changedIds.has(rel.source) && !changedIds.has(rel.target)).map((rel) => ({ status: rel.status, source: rel.source, predicate: rel.predicate, target: rel.target })), touchedLayers = new Set(changed.map((e) => e.layer));
+  for (const rel of changedRels)
+    for (const end of [rel.source, rel.target]) {
+      const element = graph.getElement(end);
+      element && touchedLayers.add(element.layer);
+    }
+  const allLayers = getAllLayerIds(), reach = {
+    touched: allLayers.filter((l) => touchedLayers.has(l)),
+    untouched: allLayers.filter((l) => !touchedLayers.has(l))
+  }, gaps = [];
+  for (const element of changed.filter((e) => e.status === "added")) {
+    const live = graph.neighbors(element.id);
+    live.length === 0 && gaps.push({
+      kind: "unconnected",
+      element: element.id,
+      detail: "Added with no relationships: nothing in the model says what it serves, realizes or uses."
+    });
+    for (const required of requiredOutgoing(element))
+      live.some((n) => {
+        if (n.direction !== "out" || n.relationship.predicate !== required.predicate)
+          return !1;
+        const other = graph.getElement(n.other);
+        return !!other && specNodeId(other) === required.destinationSpecNodeId;
+      }) || gaps.push({
+        kind: "missing-required",
+        element: element.id,
+        detail: `The catalog requires ${required.sourceSpecNodeId} --${required.predicate}--> ${required.destinationSpecNodeId}.`
+      });
+    gaps.push(...peerPatternGaps(graph, element));
+  }
+  const unwired = unwiredMode === "none" ? void 0 : presentUnwired(computeUnwired(graph), unwiredMode, new Set(reach.touched), unwiredLayers), traced = [], untraced = [], unanchored = [], intentWalk = new IntentWalk(graph, hubThreshold);
+  for (const element of changed) {
+    if (element.status === "deleted" || INTENT_LAYERS.has(element.layer))
+      continue;
+    const result = intentWalk.trace(element.id);
+    if (result.traced)
+      traced.push({ element: element.id, ...result.traced });
+    else if (untraced.push(element.id), result.unanchored) {
+      const { id, path } = result.unanchored;
+      unanchored.push({
+        element: element.id,
+        tracesTo: id,
+        path,
+        detail: `traces to added intent element ${id}, which traces to nothing`
+      });
+    }
+  }
+  const files = /* @__PURE__ */ new Map(), addFiles = (element, role) => {
+    for (const file of sourceFiles(element)) {
+      const entry = files.get(file) ?? /* @__PURE__ */ new Map();
+      entry.get(element.id) !== "changed" && entry.set(element.id, role), files.set(file, entry);
+    }
+  }, neighborIds = /* @__PURE__ */ new Set();
+  for (const element of changed) {
+    addFiles(element, "changed");
+    for (const n of graph.neighbors(element.id, { includeDeleted: !0 }))
+      changedIds.has(n.other) || neighborIds.add(n.other);
+  }
+  for (const rel of changedRels)
+    for (const end of [rel.source, rel.target])
+      changedIds.has(end) || neighborIds.add(end);
+  for (const id of neighborIds) {
+    const element = graph.getElement(id);
+    element && element.status !== "deleted" && addFiles(element, "neighbor");
+  }
+  const codeTouched = [...files.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([file, elements]) => ({
+    file,
+    elements: [...elements.entries()].map(([id, role]) => ({ id, role }))
+  })), watched = /* @__PURE__ */ new Set([...changedIds, ...neighborIds]), feedback = annotations.filter((a) => !a.resolved && watched.has(graph.resolve(a.elementId))).map((a) => ({
+    annotationId: a.id,
+    elementId: a.elementId,
+    author: a.author,
+    content: a.content,
+    tags: a.tags,
+    replies: a.replies.length
+  }));
+  return {
+    revision: graph.revision,
+    revisionToken: changesetRevisionToken(graph.changeset, graph.revision),
+    changeset: {
+      id: changeset.id,
+      name: changeset.name,
+      ...changeset.description ? { description: changeset.description } : {},
+      status: changeset.status,
+      created: changeset.created,
+      modified: changeset.modified,
+      ...drift ? { drift } : {}
+    },
+    summary: {
+      elementsAdded: changed.filter((e) => e.status === "added").length,
+      elementsUpdated: changed.filter((e) => e.status === "updated").length,
+      elementsDeleted: changed.filter((e) => e.status === "deleted").length,
+      relationshipsAdded: changedRels.filter((r) => r.status === "added").length,
+      relationshipsDeleted: changedRels.filter((r) => r.status === "deleted").length,
+      elementsAlreadyInBase: inBase.elements.length,
+      relationshipsAlreadyInBase: inBase.relationships.length
+    },
+    alreadyInBase: {
+      elements: inBase.elements.map((e) => e.id),
+      relationships: inBase.relationships.map((r) => ({ source: r.source, predicate: r.predicate, target: r.target }))
+    },
+    layers,
+    relationshipChanges,
+    reach,
+    gaps,
+    ...unwired ? { unwired } : {},
+    intent: { traced, untraced, ...unanchored.length > 0 ? { unanchored } : {} },
+    codeTouched,
+    feedback
+  };
+}
+function describeChange(graph, element) {
+  const op = element.status, connections = graph.neighbors(element.id, { includeDeleted: !0 }).map((n) => {
+    const other = graph.getElement(n.other);
+    return {
+      direction: n.direction,
+      predicate: n.relationship.predicate,
+      other: n.other,
+      ...other ? { otherName: other.name, otherLayer: other.layer } : {},
+      status: n.relationship.status
+    };
+  }), change = {
+    op,
+    id: element.id,
+    type: element.type,
+    name: element.name,
+    ...element.description ? { description: element.description } : {},
+    connections
+  };
+  return op !== "deleted" && Object.keys(element.attributes).length > 0 && (change.attributes = element.attributes), op === "updated" && element.before && (change.changedFields = diffFields(element.before, element)), change;
+}
+function diffFields(before, after) {
+  const fields = [], compare = (field, a, b) => {
+    JSON.stringify(a) !== JSON.stringify(b) && fields.push({ field, before: a, after: b });
+  };
+  compare("name", before.name, after.name), compare("description", before.description, after.description);
+  const beforeAttrs = before.attributes ?? {};
+  for (const key of /* @__PURE__ */ new Set([...Object.keys(beforeAttrs), ...Object.keys(after.attributes)]))
+    compare(`attributes.${key}`, beforeAttrs[key], after.attributes[key]);
+  return fields;
+}
+class IntentWalk {
+  graph;
+  hubThreshold;
+  anchors = /* @__PURE__ */ new Map();
+  constructor(graph, hubThreshold) {
+    this.graph = graph, this.hubThreshold = hubThreshold;
+  }
+  trace(start) {
+    let unanchored;
+    const hit = this.walk(start, (element, path) => element.status !== "added" || this.anchorOf(element.id) ? !0 : (unanchored ??= { id: element.id, path }, !1));
+    if (!hit)
+      return unanchored ? { unanchored } : {};
+    const anchor = this.graph.getElement(hit.id)?.status === "added" ? this.anchorOf(hit.id) : null;
+    return {
+      traced: {
+        tracesTo: hit.id,
+        distance: hit.path.length - 1,
+        path: hit.path,
+        ...anchor ? { anchoredBy: anchor } : {}
+      }
+    };
+  }
+  /** The existing intent element an added intent element traces to, or null. */
+  anchorOf(id) {
+    if (this.anchors.has(id))
+      return this.anchors.get(id);
+    this.anchors.set(id, null);
+    const hit = this.walk(id, (element) => element.status !== "added");
+    return this.anchors.set(id, hit), hit;
+  }
+  /**
+   * Walks from `start` and returns the first intent element `accept` takes, with the path to it.
+   * Intent elements it refuses are walked through like any other.
+   */
+  walk(start, accept) {
+    const parent = /* @__PURE__ */ new Map(), visited = /* @__PURE__ */ new Set([start]), pathTo = (id) => {
+      const path = [id];
+      for (let at = parent.get(id); at !== void 0; at = parent.get(at))
+        path.unshift(at);
+      return path;
+    };
+    let frontier = [start];
+    for (let distance = 1; distance <= INTENT_TRACE_DEPTH && frontier.length > 0; distance++) {
+      const next = [];
+      for (const id of frontier)
+        if (!(id !== start && this.graph.neighbors(id).length > this.hubThreshold))
+          for (const n of this.graph.neighbors(id)) {
+            if (visited.has(n.other))
+              continue;
+            visited.add(n.other);
+            const element = this.graph.getElement(n.other);
+            if (!(!element || element.status === "deleted")) {
+              if (parent.set(element.id, id), INTENT_LAYERS.has(element.layer) && accept(element, pathTo(element.id)))
+                return { id: element.id, path: pathTo(element.id) };
+              next.push(element.id);
+            }
+          }
+      frontier = next;
+    }
+    return null;
+  }
+}
+const PEER_MIN = 2, PEER_SHARE = 0.5;
+function peerPatternGaps(graph, element) {
+  const own = graph.neighbors(element.id);
+  if (own.length === 0)
+    return [];
+  const type = specNodeId(element), peers = /* @__PURE__ */ new Set();
+  for (const mine of own)
+    for (const theirs of graph.neighbors(mine.other)) {
+      if (theirs.relationship.predicate !== mine.relationship.predicate || theirs.direction === mine.direction)
+        continue;
+      const peer = graph.getElement(theirs.other);
+      !peer || peer.id === element.id || peer.status === "added" || peer.status === "deleted" || specNodeId(peer) === type && peers.add(peer.id);
+    }
+  if (peers.size < PEER_MIN)
+    return [];
+  const shapeOf = (n) => {
+    const other = graph.getElement(n.other);
+    return other ? `${n.direction}|${n.relationship.predicate}|${specNodeId(other)}` : null;
+  }, ownShapes = new Set(own.map(shapeOf)), shapes = /* @__PURE__ */ new Map();
+  for (const peerId of peers)
+    for (const n of graph.neighbors(peerId)) {
+      if (n.other === element.id)
+        continue;
+      const shape = shapeOf(n);
+      if (!shape || ownShapes.has(shape))
+        continue;
+      const entry = shapes.get(shape) ?? { peers: /* @__PURE__ */ new Set(), examples: [] };
+      !entry.peers.has(peerId) && entry.examples.length < 3 && entry.examples.push(describeHop(peerId, n)), entry.peers.add(peerId), shapes.set(shape, entry);
+    }
+  const threshold = Math.max(PEER_MIN, Math.ceil(peers.size * PEER_SHARE));
+  return [...shapes.entries()].filter(([, entry]) => entry.peers.size >= threshold).filter(([shape]) => {
+    const [direction, predicate, otherType] = shape.split("|");
+    return direction === "out" ? getValidRelationships(type, predicate, otherType).length > 0 : getValidRelationships(otherType, predicate, type).length > 0;
+  }).sort(([, a], [, b]) => b.peers.size - a.peers.size).map(([shape, entry]) => {
+    const [direction, predicate, otherType] = shape.split("|"), connection = direction === "out" ? `--${predicate}--> ${otherType}` : `${otherType} --${predicate}--> them`;
+    return {
+      kind: "peer-pattern",
+      element: element.id,
+      detail: `${entry.peers.size} of ${peers.size} existing ${type} elements wired like this one have ${connection}; this one has none.`,
+      examples: entry.examples
+    };
+  });
+}
+function computeUnwired(graph) {
+  const existing = /* @__PURE__ */ new Map(), added = /* @__PURE__ */ new Map();
+  for (const element of graph.elements.values()) {
+    if (element.status === "deleted")
+      continue;
+    const counts = element.status === "added" ? added : existing, type = specNodeId(element);
+    counts.set(type, (counts.get(type) ?? 0) + 1);
+  }
+  const result = [];
+  for (const element of graph.changedElements()) {
+    if (element.status !== "added" && element.status !== "updated")
+      continue;
+    const type = specNodeId(element), have = /* @__PURE__ */ new Set();
+    for (const n of graph.neighbors(element.id)) {
+      const other = graph.getElement(n.other);
+      other && other.status !== "deleted" && have.add(`${n.direction}|${n.relationship.predicate}|${specNodeId(other)}`);
+    }
+    const entries = /* @__PURE__ */ new Map(), consider = (direction, predicate, otherType) => {
+      const key = `${direction}|${predicate}|${otherType}`;
+      if (have.has(key) || entries.has(key))
+        return;
+      const self = otherType === type ? 1 : 0, existingCount = (existing.get(otherType) ?? 0) - (element.status === "added" ? 0 : self), addedCount = (added.get(otherType) ?? 0) - (element.status === "added" ? self : 0);
+      entries.set(key, { direction, predicate, otherType, existingCount, addedCount });
+    };
+    for (const spec of RELATIONSHIPS_BY_SOURCE.get(type) ?? [])
+      consider("out", spec.predicate, spec.destinationSpecNodeId);
+    for (const spec of RELATIONSHIPS_BY_DESTINATION.get(type) ?? [])
+      consider("in", spec.predicate, spec.sourceSpecNodeId);
+    const layerOf = (specId) => specId.split(".")[0], all = [...entries.values()], byLayer = orderedLayers(all.map((e) => layerOf(e.otherType))).map((layer) => ({
+      layer,
+      entries: all.filter((e) => layerOf(e.otherType) === layer).sort((a, b) => (a.direction === b.direction ? 0 : a.direction === "out" ? -1 : 1) || a.predicate.localeCompare(b.predicate) || a.otherType.localeCompare(b.otherType))
+    }));
+    result.push({ element: element.id, type, byLayer });
+  }
+  return result;
+}
+function presentUnwired(computed, mode, reachedLayers, layerFilter) {
+  const known = new Set(getAllLayerIds()), filter = layerFilter ? new Set(layerFilter) : void 0, unknownLayers = layerFilter?.filter((l) => !known.has(l)) ?? [], elements = computed.map(({ element, type, byLayer }) => {
+    const shown = byLayer.filter((l) => !filter || filter.has(l.layer)).map((l) => {
+      const count = l.entries.length;
+      if (mode === "full")
+        return { layer: l.layer, count, entries: l.entries };
+      const inModel = l.entries.filter((e) => e.existingCount + e.addedCount > 0), typesNotInModel = count - inModel.length, withEntries = reachedLayers.has(l.layer) || !!filter?.has(l.layer);
+      return {
+        layer: l.layer,
+        count,
+        ...withEntries ? { entries: inModel } : {},
+        ...typesNotInModel > 0 ? { typesNotInModel } : {}
+      };
+    });
+    return { element, type, total: shown.reduce((sum, l) => sum + l.count, 0), byLayer: shown };
+  });
+  return {
+    mode,
+    ...layerFilter ? { layers: layerFilter } : {},
+    ...unknownLayers.length > 0 ? { unknownLayers } : {},
+    elements
+  };
+}
+function unwiredKey(element, entry) {
+  return `${element}|${entry.direction}|${entry.predicate}|${entry.otherType}`;
+}
+function requiredOutgoing(element) {
+  return getValidRelationships(specNodeId(element)).filter((r) => r.required);
+}
+function specNodeId(element) {
+  return `${element.layer}.${normalizeNodeType(element.layer, element.type)}`;
+}
+function describeHop(from, neighbor) {
+  const { predicate, status } = neighbor.relationship, suffix = status === "unchanged" ? "" : ` (${status} by this changeset)`;
+  return neighbor.direction === "out" ? `${from} --${predicate}--> ${neighbor.other}${suffix}` : `${neighbor.other} --${predicate}--> ${from}${suffix}`;
+}
+function sourceFiles(element) {
+  const locations = element.sourceReference?.locations ?? [];
+  return [...new Set(locations.map((l) => l.file).filter((f) => !!f))];
+}
+function orderedLayers(layers) {
+  const present = new Set(layers), known = getAllLayerIds().filter((l) => present.has(l)), unknown = [...present].filter((l) => !known.includes(l)).sort();
+  return [...known, ...unknown];
+}
+export {
+  DEFAULT_HUB_THRESHOLD,
+  INTENT_LAYERS,
+  buildBrief,
+  computeImpact,
+  computeUnwired,
+  unwiredKey
+};
+//# sourceMappingURL=changeset-analysis.js.map