@contractspec/bundle.workspace 4.0.3 → 4.1.2

package/dist/ai/agents/unified-adapter.d.ts

@@ -2,8 +2,8 @@
  * Adapter for UnifiedAgent to work with Workspace AgentOrchestrator.
  */
 import { type UnifiedAgentConfig } from '@contractspec/lib.ai-agent/agent/unified-agent';
-import type { AgentSpec } from '@contractspec/lib.ai-agent/spec';
 import type { AgentMode } from '@contractspec/lib.contracts-spec';
+import type { AgentSpec } from '@contractspec/lib.contracts-spec/agent';
 import type { AgentProvider, AgentResult, AgentTask } from './types';
 export declare class UnifiedAgentAdapter implements AgentProvider {
     readonly name: AgentMode;

package/dist/index.js

@@ -397,7 +397,6 @@ var DEFAULT_FS_IGNORES = [
   "**/*.d.ts",
   "**/importer/**",
   "**/exporter/**",
-  "**/docs/**/*.docblock.ts",
   "**/docs/presentations.ts"
 ];
 
@@ -4349,6 +4348,93 @@ async function runDepsChecks(adapters, options) {
   }
   return issues;
 }
+// src/services/docs/docblock-audit.ts
+import {
+  analyzePackageDocBlocks
+} from "@contractspec/module.workspace";
+var PACKAGE_GLOB_IGNORES = [
+  "**/node_modules/**",
+  "**/dist/**",
+  "**/.turbo/**",
+  "**/.next/**"
+];
+async function discoverWorkspaceDocPackages(fs5, workspaceRoot) {
+  const packageJsonFiles = await fs5.glob({
+    pattern: "packages/**/package.json",
+    cwd: workspaceRoot,
+    ignore: PACKAGE_GLOB_IGNORES
+  });
+  const discovered = new Map;
+  for (const packageJsonFile of packageJsonFiles) {
+    const packageRoot = fs5.dirname(packageJsonFile);
+    const srcRoot = fs5.join(packageRoot, "src");
+    if (!await fs5.exists(srcRoot)) {
+      continue;
+    }
+    try {
+      const packageJson = JSON.parse(await fs5.readFile(packageJsonFile));
+      discovered.set(packageRoot, {
+        packageName: packageJson.name ?? fs5.relative(workspaceRoot, packageRoot),
+        packageRoot,
+        srcRoot
+      });
+    } catch {
+      continue;
+    }
+  }
+  const rootPackageJson = fs5.join(workspaceRoot, "package.json");
+  const rootSrc = fs5.join(workspaceRoot, "src");
+  if (await fs5.exists(rootPackageJson) && await fs5.exists(rootSrc)) {
+    try {
+      const packageJson = JSON.parse(await fs5.readFile(rootPackageJson));
+      discovered.set(workspaceRoot, {
+        packageName: packageJson.name ?? workspaceRoot,
+        packageRoot: workspaceRoot,
+        srcRoot: rootSrc
+      });
+    } catch {}
+  }
+  return [...discovered.values()].sort((left, right) => left.packageRoot.localeCompare(right.packageRoot));
+}
+async function analyzeWorkspaceDocBlocks(fs5, workspaceRoot) {
+  const diagnostics = [];
+  const packages = await discoverWorkspaceDocPackages(fs5, workspaceRoot);
+  for (const pkg of packages) {
+    const result = analyzePackageDocBlocks({
+      packageName: pkg.packageName,
+      srcRoot: pkg.srcRoot
+    });
+    for (const diagnostic of result.diagnostics) {
+      diagnostics.push({
+        ...diagnostic,
+        packageName: pkg.packageName,
+        packageRoot: pkg.packageRoot,
+        srcRoot: pkg.srcRoot
+      });
+    }
+  }
+  return diagnostics;
+}
+
+// src/services/ci-check/checks/docs.ts
+async function runDocsChecks(adapters, options) {
+  const workspaceRoot = options.workspaceRoot ?? process.cwd();
+  const diagnostics = await analyzeWorkspaceDocBlocks(adapters.fs, workspaceRoot);
+  return diagnostics.map((diagnostic) => ({
+    ruleId: diagnostic.ruleId,
+    severity: diagnostic.severity === "warning" ? "warning" : "error",
+    message: diagnostic.message,
+    category: "docs",
+    file: diagnostic.file,
+    line: diagnostic.line,
+    column: diagnostic.column,
+    context: {
+      packageName: diagnostic.packageName,
+      packageRoot: diagnostic.packageRoot,
+      ...diagnostic.context
+    }
+  }));
+}
 // src/services/doctor/checks/ai.ts
 async function runAiChecks(fs5, ctx, prompts) {
   const results = [];
@@ -4627,7 +4713,7 @@ function generateContractsrcConfig(options) {
       type: "biome"
     },
     ci: {
-      checks: ["structure", "integrity", "deps", "doctor", "policy"],
+      checks: ["structure", "integrity", "deps", "doctor", "docs", "policy"],
       failOnWarnings: false,
       uploadSarif: true
     },
@@ -5437,6 +5523,34 @@ async function checkContractsLibrary(fs5, ctx) {
     };
   }
 }
+// src/services/doctor/checks/docs.ts
+async function runDocChecks(fs5, ctx) {
+  const diagnostics = await analyzeWorkspaceDocBlocks(fs5, ctx.workspaceRoot);
+  if (diagnostics.length === 0) {
+    return [
+      {
+        category: "docs",
+        name: "Same-File DocBlocks",
+        status: "pass",
+        message: "All analyzed packages follow the same-file DocBlock rules."
+      }
+    ];
+  }
+  return diagnostics.map((diagnostic) => ({
+    category: "docs",
+    name: `Same-File DocBlocks (${diagnostic.packageName})`,
+    status: diagnostic.severity === "warning" ? "warn" : "fail",
+    message: diagnostic.message,
+    details: fs5.relative(ctx.workspaceRoot, diagnostic.file),
+    context: {
+      ruleId: diagnostic.ruleId,
+      file: diagnostic.file,
+      line: diagnostic.line,
+      column: diagnostic.column,
+      packageName: diagnostic.packageName
+    }
+  }));
+}
 // src/services/layer-discovery.ts
 import {
   isExampleFile,
@@ -6346,6 +6460,7 @@ var ALL_CHECK_CATEGORIES = [
   "config",
   "mcp",
   "deps",
+  "docs",
   "workspace",
   "ai",
   "layers"
@@ -6355,6 +6470,7 @@ var CHECK_CATEGORY_LABELS = {
   config: "Configuration Files",
   mcp: "MCP Server",
   deps: "Dependencies",
+  docs: "DocBlock Ownership",
   workspace: "Workspace Structure",
   ai: "AI Provider",
   layers: "Contract Layers"
@@ -6367,6 +6483,7 @@ var defaultDoctorDependencies = {
     runConfigChecks,
     runMcpChecks,
     runDepsChecks: runDepsChecks2,
+    runDocChecks,
     runWorkspaceChecks,
     runAiChecks,
     runLayerChecks
@@ -6450,6 +6567,8 @@ async function runCategoryChecks(category, fs5, ctx, prompts, checks) {
       return checks.runMcpChecks(fs5, ctx);
     case "deps":
       return checks.runDepsChecks(fs5, ctx);
+    case "docs":
+      return checks.runDocChecks(fs5, ctx);
     case "workspace":
       return checks.runWorkspaceChecks(fs5, ctx);
     case "ai":
@@ -6532,13 +6651,14 @@ import path3 from "path";
 
 // src/services/generate-artifacts.ts
 import path2 from "path";
-
 // src/services/docs/docs-service.ts
 import {
-  defaultDocRegistry
+  packageDocBlocks
 } from "@contractspec/lib.contracts-spec/docs";
 import {
+  buildPackageDocManifest,
   convertSpecToDocBlock,
+  extractModuleDocData,
   loadSpecFromSource,
   scanAllSpecsFromSource as scanAllSpecsFromSource2,
   scanSpecSource as scanSpecSource3
@@ -6628,6 +6748,14 @@ async function generateDocsFromSpecs(specFiles, options, adapters) {
     } catch (_err) {}
   }
   resolver.initialize(scanResults);
+  const authoredEntries = await loadAuthoredDocEntriesFromSourceFiles(specFiles, adapters);
+  for (const authoredEntry of authoredEntries) {
+    blocks.push(authoredEntry.entry.block);
+    logger3.debug(`Loaded authored doc ${authoredEntry.entry.id}`);
+    if (options.outputDir) {
+      await writeDocBlockFile(authoredEntry.entry.block, authoredEntry.filePath, options.outputDir, resolver, fs5);
+    }
+  }
   for (const file of specFiles) {
     try {
       const parsedList = await loadSpecFromSource(file);
@@ -6639,26 +6767,12 @@ async function generateDocsFromSpecs(specFiles, options, adapters) {
         const block = convertSpecToDocBlock(parsed, {
           rootPath: options.rootPath
         });
-        defaultDocRegistry.register(block);
         blocks.push(block);
         logger3.debug(`Generated doc for ${block.id}`);
         if (!options.outputDir) {
           continue;
         }
-        const moduleDef = resolver.resolve(file);
-        let targetDir = options.outputDir;
-        if (moduleDef) {
-          targetDir = path.join(options.outputDir, moduleDef.key);
-        } else {
-          targetDir = path.join(options.outputDir, "_common");
-        }
-        await fs5.mkdir(targetDir);
-        const filename = `${block.id}.md`;
-        const filePath = path.join(targetDir, filename);
-        const generatedContent = `<!-- @generated - This file was generated by ContractSpec. Do not edit manually. -->
-
-${block.body}`;
-        await fs5.writeFile(filePath, generatedContent);
+        await writeDocBlockFile(block, file, options.outputDir, resolver, fs5);
       }
     } catch (error) {
       logger3.error(`Error processing ${file}: ${error instanceof Error ? error.message : String(error)}`);
@@ -6669,6 +6783,36 @@ ${block.body}`;
   }
   return { blocks, count: blocks.length };
 }
+async function loadAuthoredDocBlocksFromSourceFiles(sourceFiles, adapters) {
+  const entries = await loadAuthoredDocEntriesFromSourceFiles(sourceFiles, adapters);
+  return entries.map(({ entry }) => entry.block);
+}
+function loadPackageAuthoredDocBlocks(packageName, srcRoot) {
+  return packageDocBlocks(buildPackageDocManifest({ packageName, srcRoot }));
+}
+async function loadAuthoredDocEntriesFromSourceFiles(sourceFiles, adapters) {
+  const uniqueFiles = [...new Set(sourceFiles)].sort((left, right) => left.localeCompare(right));
+  const entries = [];
+  for (const filePath of uniqueFiles) {
+    const sourceText = await adapters.fs.readFile(filePath);
+    const sourceModule = filePath.replace(/\\/g, "/").replace(/\.[cm]?[jt]sx?$/, "");
+    const moduleData = extractModuleDocData(sourceText, filePath, sourceModule);
+    for (const entry of moduleData.entries) {
+      entries.push({ entry, filePath });
+    }
+  }
+  return entries;
+}
+async function writeDocBlockFile(block, file, outputDir, resolver, fs5) {
+  const moduleDef = resolver.resolve(file);
+  const targetDir = moduleDef ? path.join(outputDir, moduleDef.key) : path.join(outputDir, "_common");
+  await fs5.mkdir(targetDir);
+  const filePath = path.join(targetDir, `${block.id}.md`);
+  const generatedContent = `<!-- @generated - This file was generated by ContractSpec. Do not edit manually. -->
+
+${block.body}`;
+  await fs5.writeFile(filePath, generatedContent);
+}
 // src/services/generate-artifacts.ts
 async function generateArtifacts(adapters, contractsDir, generatedDir, rootPath) {
   if (!await adapters.fs.exists(contractsDir)) {}
@@ -8156,6 +8300,7 @@ function createCategorySummary(category, issues, durationMs) {
     integrity: "Contract Integrity Analysis",
     deps: "Dependency Analysis",
     doctor: "Installation Health",
+    docs: "DocBlock Ownership",
     policy: "Contract Policy Enforcement",
     handlers: "Handler Implementation",
     tests: "Test Coverage",
@@ -8203,7 +8348,7 @@ async function getGitInfo(fs5) {
 }
 function getChecksToRun(options) {
   const configuredChecks = options.config?.ci?.checks;
-  const allCategories = configuredChecks && configuredChecks.length > 0 ? [...configuredChecks] : ["structure", "integrity", "deps", "doctor"];
+  const allCategories = configuredChecks && configuredChecks.length > 0 ? [...configuredChecks] : ["structure", "integrity", "deps", "doctor", "docs"];
   if (options.checkHandlers) {
     allCategories.push("handlers");
   }
@@ -8261,6 +8406,12 @@ async function runCIChecks(adapters, options = {}) {
     issues.push(...doctorIssues);
     categorySummaries.push(createCategorySummary("doctor", doctorIssues, Date.now() - categoryStart));
   }
+  if (checksToRun.includes("docs")) {
+    const categoryStart = Date.now();
+    const docsIssues = await runDocsChecks(adapters, options);
+    issues.push(...docsIssues);
+    categorySummaries.push(createCategorySummary("docs", docsIssues, Date.now() - categoryStart));
+  }
   if (checksToRun.includes("policy")) {
     const categoryStart = Date.now();
     const policyIssues = await runPolicyChecks(adapters, options);
@@ -8339,6 +8490,7 @@ var ALL_CI_CHECK_CATEGORIES = [
   "integrity",
   "deps",
   "doctor",
+  "docs",
   "policy",
   "handlers",
   "tests",
@@ -8353,6 +8505,7 @@ var CI_CHECK_CATEGORY_LABELS = {
   integrity: "Contract Integrity Analysis",
   deps: "Dependency Analysis",
   doctor: "Installation Health",
+  docs: "DocBlock Ownership",
   policy: "Contract Policy Enforcement",
   handlers: "Handler Implementation",
   tests: "Test Coverage",
@@ -11643,7 +11796,8 @@ __export(exports_impact, {
   formatMinimalComment: () => formatMinimalComment,
   formatJson: () => formatJson2,
   formatCheckRun: () => formatCheckRun,
-  detectImpact: () => detectImpact
+  detectImpact: () => detectImpact,
+  ImpactDetectionOverviewDocBlock: () => ImpactDetectionOverviewDocBlock
 });
 
 // src/services/impact/formatters.ts
@@ -11870,6 +12024,63 @@ function computeSnapshotDiffs(baseSpecs, headSpecs) {
   }
   return diffs;
 }
+
+// src/services/impact/index.ts
+var ImpactDetectionOverviewDocBlock = {
+  id: "feature.impact-detection.overview",
+  title: "Contract Impact Detection",
+  kind: "goal",
+  visibility: "public",
+  route: "/docs/features/impact-detection",
+  body: `
+# Contract Impact Detection
+
+Automated detection and classification of breaking changes in ContractSpec APIs.
+
+## Features
+
+- **Snapshot Generation**: Creates canonical, deterministic representations of contracts
+- **Deep Diff Engine**: Field-level comparison of input/output schemas
+- **Breaking Change Classification**: Automatic classification using 16 rules
+- **Multiple Output Formats**: JSON, Markdown, Text, GitHub Check Run
+- **GitHub Integration**: PR comments and check runs
+- **CLI Tool**: \`contractspec impact\` command
+
+## Quick Start
+
+### CLI Usage
+
+\`\`\`bash
+# Basic usage
+contractspec impact
+
+# Compare against specific baseline
+contractspec impact --baseline origin/main
+
+# Get JSON output
+contractspec impact --format json
+\`\`\`
+
+### GitHub Action
+
+\`\`\`yaml
+- uses: lssm-tech/contractspec-action@v1
+  with:
+    mode: impact
+    pr-comment: true
+    fail-on-breaking: true
+\`\`\`
+
+## Architecture
+
+The system consists of three layers:
+
+1. **Analysis Modules** (module package): Snapshot, Deep Diff, Classifier
+2. **Impact Service** (bundle package): Orchestration + Formatters
+3. **Integrations**: CLI command + GitHub Action
+  `,
+  tags: ["impact-detection", "breaking-changes", "ci-cd"]
+};
 // src/services/import/import-service.ts
 import {
   detectFramework,
@@ -17715,6 +17926,8 @@ export {
   module,
   mergeMonorepoConfigs,
   loadWorkspaceConfig,
+  loadPackageAuthoredDocBlocks,
+  loadAuthoredDocBlocksFromSourceFiles,
   listTests,
   listSpecsForView,
   listSpecs,
@@ -17838,6 +18051,7 @@ export {
   claudeCodeAdapter,
   cacheKeyToString,
   buildSpec,
+  analyzeWorkspaceDocBlocks,
   analyzeIntegrity,
   analyzeGap,
   analyzeDeps,

package/dist/node/index.js

@@ -397,7 +397,6 @@ var DEFAULT_FS_IGNORES = [
   "**/*.d.ts",
   "**/importer/**",
   "**/exporter/**",
-  "**/docs/**/*.docblock.ts",
   "**/docs/presentations.ts"
 ];
 
@@ -4349,6 +4348,93 @@ async function runDepsChecks(adapters, options) {
   }
   return issues;
 }
+// src/services/docs/docblock-audit.ts
+import {
+  analyzePackageDocBlocks
+} from "@contractspec/module.workspace";
+var PACKAGE_GLOB_IGNORES = [
+  "**/node_modules/**",
+  "**/dist/**",
+  "**/.turbo/**",
+  "**/.next/**"
+];
+async function discoverWorkspaceDocPackages(fs5, workspaceRoot) {
+  const packageJsonFiles = await fs5.glob({
+    pattern: "packages/**/package.json",
+    cwd: workspaceRoot,
+    ignore: PACKAGE_GLOB_IGNORES
+  });
+  const discovered = new Map;
+  for (const packageJsonFile of packageJsonFiles) {
+    const packageRoot = fs5.dirname(packageJsonFile);
+    const srcRoot = fs5.join(packageRoot, "src");
+    if (!await fs5.exists(srcRoot)) {
+      continue;
+    }
+    try {
+      const packageJson = JSON.parse(await fs5.readFile(packageJsonFile));
+      discovered.set(packageRoot, {
+        packageName: packageJson.name ?? fs5.relative(workspaceRoot, packageRoot),
+        packageRoot,
+        srcRoot
+      });
+    } catch {
+      continue;
+    }
+  }
+  const rootPackageJson = fs5.join(workspaceRoot, "package.json");
+  const rootSrc = fs5.join(workspaceRoot, "src");
+  if (await fs5.exists(rootPackageJson) && await fs5.exists(rootSrc)) {
+    try {
+      const packageJson = JSON.parse(await fs5.readFile(rootPackageJson));
+      discovered.set(workspaceRoot, {
+        packageName: packageJson.name ?? workspaceRoot,
+        packageRoot: workspaceRoot,
+        srcRoot: rootSrc
+      });
+    } catch {}
+  }
+  return [...discovered.values()].sort((left, right) => left.packageRoot.localeCompare(right.packageRoot));
+}
+async function analyzeWorkspaceDocBlocks(fs5, workspaceRoot) {
+  const diagnostics = [];
+  const packages = await discoverWorkspaceDocPackages(fs5, workspaceRoot);
+  for (const pkg of packages) {
+    const result = analyzePackageDocBlocks({
+      packageName: pkg.packageName,
+      srcRoot: pkg.srcRoot
+    });
+    for (const diagnostic of result.diagnostics) {
+      diagnostics.push({
+        ...diagnostic,
+        packageName: pkg.packageName,
+        packageRoot: pkg.packageRoot,
+        srcRoot: pkg.srcRoot
+      });
+    }
+  }
+  return diagnostics;
+}
+
+// src/services/ci-check/checks/docs.ts
+async function runDocsChecks(adapters, options) {
+  const workspaceRoot = options.workspaceRoot ?? process.cwd();
+  const diagnostics = await analyzeWorkspaceDocBlocks(adapters.fs, workspaceRoot);
+  return diagnostics.map((diagnostic) => ({
+    ruleId: diagnostic.ruleId,
+    severity: diagnostic.severity === "warning" ? "warning" : "error",
+    message: diagnostic.message,
+    category: "docs",
+    file: diagnostic.file,
+    line: diagnostic.line,
+    column: diagnostic.column,
+    context: {
+      packageName: diagnostic.packageName,
+      packageRoot: diagnostic.packageRoot,
+      ...diagnostic.context
+    }
+  }));
+}
 // src/services/doctor/checks/ai.ts
 async function runAiChecks(fs5, ctx, prompts) {
   const results = [];
@@ -4627,7 +4713,7 @@ function generateContractsrcConfig(options) {
       type: "biome"
     },
     ci: {
-      checks: ["structure", "integrity", "deps", "doctor", "policy"],
+      checks: ["structure", "integrity", "deps", "doctor", "docs", "policy"],
       failOnWarnings: false,
       uploadSarif: true
     },
@@ -5437,6 +5523,34 @@ async function checkContractsLibrary(fs5, ctx) {
     };
   }
 }
+// src/services/doctor/checks/docs.ts
+async function runDocChecks(fs5, ctx) {
+  const diagnostics = await analyzeWorkspaceDocBlocks(fs5, ctx.workspaceRoot);
+  if (diagnostics.length === 0) {
+    return [
+      {
+        category: "docs",
+        name: "Same-File DocBlocks",
+        status: "pass",
+        message: "All analyzed packages follow the same-file DocBlock rules."
+      }
+    ];
+  }
+  return diagnostics.map((diagnostic) => ({
+    category: "docs",
+    name: `Same-File DocBlocks (${diagnostic.packageName})`,
+    status: diagnostic.severity === "warning" ? "warn" : "fail",
+    message: diagnostic.message,
+    details: fs5.relative(ctx.workspaceRoot, diagnostic.file),
+    context: {
+      ruleId: diagnostic.ruleId,
+      file: diagnostic.file,
+      line: diagnostic.line,
+      column: diagnostic.column,
+      packageName: diagnostic.packageName
+    }
+  }));
+}
 // src/services/layer-discovery.ts
 import {
   isExampleFile,
@@ -6346,6 +6460,7 @@ var ALL_CHECK_CATEGORIES = [
   "config",
   "mcp",
   "deps",
+  "docs",
   "workspace",
   "ai",
   "layers"
@@ -6355,6 +6470,7 @@ var CHECK_CATEGORY_LABELS = {
   config: "Configuration Files",
   mcp: "MCP Server",
   deps: "Dependencies",
+  docs: "DocBlock Ownership",
   workspace: "Workspace Structure",
   ai: "AI Provider",
   layers: "Contract Layers"
@@ -6367,6 +6483,7 @@ var defaultDoctorDependencies = {
     runConfigChecks,
     runMcpChecks,
     runDepsChecks: runDepsChecks2,
+    runDocChecks,
     runWorkspaceChecks,
     runAiChecks,
     runLayerChecks
@@ -6450,6 +6567,8 @@ async function runCategoryChecks(category, fs5, ctx, prompts, checks) {
       return checks.runMcpChecks(fs5, ctx);
     case "deps":
       return checks.runDepsChecks(fs5, ctx);
+    case "docs":
+      return checks.runDocChecks(fs5, ctx);
     case "workspace":
       return checks.runWorkspaceChecks(fs5, ctx);
     case "ai":
@@ -6532,13 +6651,14 @@ import path3 from "path";
 
 // src/services/generate-artifacts.ts
 import path2 from "path";
-
 // src/services/docs/docs-service.ts
 import {
-  defaultDocRegistry
+  packageDocBlocks
 } from "@contractspec/lib.contracts-spec/docs";
 import {
+  buildPackageDocManifest,
   convertSpecToDocBlock,
+  extractModuleDocData,
   loadSpecFromSource,
   scanAllSpecsFromSource as scanAllSpecsFromSource2,
   scanSpecSource as scanSpecSource3
@@ -6628,6 +6748,14 @@ async function generateDocsFromSpecs(specFiles, options, adapters) {
     } catch (_err) {}
   }
   resolver.initialize(scanResults);
+  const authoredEntries = await loadAuthoredDocEntriesFromSourceFiles(specFiles, adapters);
+  for (const authoredEntry of authoredEntries) {
+    blocks.push(authoredEntry.entry.block);
+    logger3.debug(`Loaded authored doc ${authoredEntry.entry.id}`);
+    if (options.outputDir) {
+      await writeDocBlockFile(authoredEntry.entry.block, authoredEntry.filePath, options.outputDir, resolver, fs5);
+    }
+  }
   for (const file of specFiles) {
     try {
       const parsedList = await loadSpecFromSource(file);
@@ -6639,26 +6767,12 @@ async function generateDocsFromSpecs(specFiles, options, adapters) {
         const block = convertSpecToDocBlock(parsed, {
           rootPath: options.rootPath
         });
-        defaultDocRegistry.register(block);
         blocks.push(block);
         logger3.debug(`Generated doc for ${block.id}`);
         if (!options.outputDir) {
           continue;
         }
-        const moduleDef = resolver.resolve(file);
-        let targetDir = options.outputDir;
-        if (moduleDef) {
-          targetDir = path.join(options.outputDir, moduleDef.key);
-        } else {
-          targetDir = path.join(options.outputDir, "_common");
-        }
-        await fs5.mkdir(targetDir);
-        const filename = `${block.id}.md`;
-        const filePath = path.join(targetDir, filename);
-        const generatedContent = `<!-- @generated - This file was generated by ContractSpec. Do not edit manually. -->
-
-${block.body}`;
-        await fs5.writeFile(filePath, generatedContent);
+        await writeDocBlockFile(block, file, options.outputDir, resolver, fs5);
       }
     } catch (error) {
       logger3.error(`Error processing ${file}: ${error instanceof Error ? error.message : String(error)}`);
@@ -6669,6 +6783,36 @@ ${block.body}`;
   }
   return { blocks, count: blocks.length };
 }
+async function loadAuthoredDocBlocksFromSourceFiles(sourceFiles, adapters) {
+  const entries = await loadAuthoredDocEntriesFromSourceFiles(sourceFiles, adapters);
+  return entries.map(({ entry }) => entry.block);
+}
+function loadPackageAuthoredDocBlocks(packageName, srcRoot) {
+  return packageDocBlocks(buildPackageDocManifest({ packageName, srcRoot }));
+}
+async function loadAuthoredDocEntriesFromSourceFiles(sourceFiles, adapters) {
+  const uniqueFiles = [...new Set(sourceFiles)].sort((left, right) => left.localeCompare(right));
+  const entries = [];
+  for (const filePath of uniqueFiles) {
+    const sourceText = await adapters.fs.readFile(filePath);
+    const sourceModule = filePath.replace(/\\/g, "/").replace(/\.[cm]?[jt]sx?$/, "");
+    const moduleData = extractModuleDocData(sourceText, filePath, sourceModule);
+    for (const entry of moduleData.entries) {
+      entries.push({ entry, filePath });
+    }
+  }
+  return entries;
+}
+async function writeDocBlockFile(block, file, outputDir, resolver, fs5) {
+  const moduleDef = resolver.resolve(file);
+  const targetDir = moduleDef ? path.join(outputDir, moduleDef.key) : path.join(outputDir, "_common");
+  await fs5.mkdir(targetDir);
+  const filePath = path.join(targetDir, `${block.id}.md`);
+  const generatedContent = `<!-- @generated - This file was generated by ContractSpec. Do not edit manually. -->
+
+${block.body}`;
+  await fs5.writeFile(filePath, generatedContent);
+}
 // src/services/generate-artifacts.ts
 async function generateArtifacts(adapters, contractsDir, generatedDir, rootPath) {
   if (!await adapters.fs.exists(contractsDir)) {}
@@ -8156,6 +8300,7 @@ function createCategorySummary(category, issues, durationMs) {
     integrity: "Contract Integrity Analysis",
     deps: "Dependency Analysis",
     doctor: "Installation Health",
+    docs: "DocBlock Ownership",
     policy: "Contract Policy Enforcement",
     handlers: "Handler Implementation",
     tests: "Test Coverage",
@@ -8203,7 +8348,7 @@ async function getGitInfo(fs5) {
 }
 function getChecksToRun(options) {
   const configuredChecks = options.config?.ci?.checks;
-  const allCategories = configuredChecks && configuredChecks.length > 0 ? [...configuredChecks] : ["structure", "integrity", "deps", "doctor"];
+  const allCategories = configuredChecks && configuredChecks.length > 0 ? [...configuredChecks] : ["structure", "integrity", "deps", "doctor", "docs"];
   if (options.checkHandlers) {
     allCategories.push("handlers");
   }
@@ -8261,6 +8406,12 @@ async function runCIChecks(adapters, options = {}) {
     issues.push(...doctorIssues);
     categorySummaries.push(createCategorySummary("doctor", doctorIssues, Date.now() - categoryStart));
   }
+  if (checksToRun.includes("docs")) {
+    const categoryStart = Date.now();
+    const docsIssues = await runDocsChecks(adapters, options);
+    issues.push(...docsIssues);
+    categorySummaries.push(createCategorySummary("docs", docsIssues, Date.now() - categoryStart));
+  }
   if (checksToRun.includes("policy")) {
     const categoryStart = Date.now();
     const policyIssues = await runPolicyChecks(adapters, options);
@@ -8339,6 +8490,7 @@ var ALL_CI_CHECK_CATEGORIES = [
   "integrity",
   "deps",
   "doctor",
+  "docs",
   "policy",
   "handlers",
   "tests",
@@ -8353,6 +8505,7 @@ var CI_CHECK_CATEGORY_LABELS = {
   integrity: "Contract Integrity Analysis",
   deps: "Dependency Analysis",
   doctor: "Installation Health",
+  docs: "DocBlock Ownership",
   policy: "Contract Policy Enforcement",
   handlers: "Handler Implementation",
   tests: "Test Coverage",
@@ -11643,7 +11796,8 @@ __export(exports_impact, {
   formatMinimalComment: () => formatMinimalComment,
   formatJson: () => formatJson2,
   formatCheckRun: () => formatCheckRun,
-  detectImpact: () => detectImpact
+  detectImpact: () => detectImpact,
+  ImpactDetectionOverviewDocBlock: () => ImpactDetectionOverviewDocBlock
 });
 
 // src/services/impact/formatters.ts
@@ -11870,6 +12024,63 @@ function computeSnapshotDiffs(baseSpecs, headSpecs) {
   }
   return diffs;
 }
+
+// src/services/impact/index.ts
+var ImpactDetectionOverviewDocBlock = {
+  id: "feature.impact-detection.overview",
+  title: "Contract Impact Detection",
+  kind: "goal",
+  visibility: "public",
+  route: "/docs/features/impact-detection",
+  body: `
+# Contract Impact Detection
+
+Automated detection and classification of breaking changes in ContractSpec APIs.
+
+## Features
+
+- **Snapshot Generation**: Creates canonical, deterministic representations of contracts
+- **Deep Diff Engine**: Field-level comparison of input/output schemas
+- **Breaking Change Classification**: Automatic classification using 16 rules
+- **Multiple Output Formats**: JSON, Markdown, Text, GitHub Check Run
+- **GitHub Integration**: PR comments and check runs
+- **CLI Tool**: \`contractspec impact\` command
+
+## Quick Start
+
+### CLI Usage
+
+\`\`\`bash
+# Basic usage
+contractspec impact
+
+# Compare against specific baseline
+contractspec impact --baseline origin/main
+
+# Get JSON output
+contractspec impact --format json
+\`\`\`
+
+### GitHub Action
+
+\`\`\`yaml
+- uses: lssm-tech/contractspec-action@v1
+  with:
+    mode: impact
+    pr-comment: true
+    fail-on-breaking: true
+\`\`\`
+
+## Architecture
+
+The system consists of three layers:
+
+1. **Analysis Modules** (module package): Snapshot, Deep Diff, Classifier
+2. **Impact Service** (bundle package): Orchestration + Formatters
+3. **Integrations**: CLI command + GitHub Action
+  `,
+  tags: ["impact-detection", "breaking-changes", "ci-cd"]
+};
 // src/services/import/import-service.ts
 import {
   detectFramework,
@@ -17715,6 +17926,8 @@ export {
   module,
   mergeMonorepoConfigs,
   loadWorkspaceConfig,
+  loadPackageAuthoredDocBlocks,
+  loadAuthoredDocBlocksFromSourceFiles,
   listTests,
   listSpecsForView,
   listSpecs,
@@ -17838,6 +18051,7 @@ export {
   claudeCodeAdapter,
   cacheKeyToString,
   buildSpec,
+  analyzeWorkspaceDocBlocks,
   analyzeIntegrity,
   analyzeGap,
   analyzeDeps,

package/dist/services/ci-check/checks/docs.d.ts

@@ -0,0 +1,7 @@
+import type { FsAdapter } from '../../../ports/fs';
+import type { LoggerAdapter } from '../../../ports/logger';
+import type { CICheckOptions, CIIssue } from '../types';
+export declare function runDocsChecks(adapters: {
+    fs: FsAdapter;
+    logger: LoggerAdapter;
+}, options: CICheckOptions): Promise<CIIssue[]>;

package/dist/services/ci-check/checks/docs.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/ci-check/checks/index.d.ts

@@ -3,6 +3,7 @@
  */
 export { runCoverageChecks } from './coverage';
 export { runDepsChecks } from './deps';
+export { runDocsChecks } from './docs';
 export { runDoctorChecks } from './doctor';
 export { runDriftChecks } from './drift';
 export { runHandlerChecks } from './handlers';

package/dist/services/ci-check/types.d.ts

@@ -7,7 +7,7 @@ import type { ContractsrcConfig, ResolvedContractsrcConfig } from '@contractspec
 /**
  * Categories of CI checks.
  */
-export type CICheckCategory = 'structure' | 'integrity' | 'deps' | 'doctor' | 'policy' | 'handlers' | 'tests' | 'test-refs' | 'coverage' | 'implementation' | 'layers' | 'drift';
+export type CICheckCategory = 'structure' | 'integrity' | 'deps' | 'doctor' | 'docs' | 'policy' | 'handlers' | 'tests' | 'test-refs' | 'coverage' | 'implementation' | 'layers' | 'drift';
 /**
  * All available CI check categories.
  */

package/dist/services/docs/docblock-audit.d.ts

@@ -0,0 +1,8 @@
+import { type DocBlockDiagnostic } from '@contractspec/module.workspace';
+import type { FsAdapter } from '../../ports/fs';
+export interface WorkspaceDocBlockDiagnostic extends DocBlockDiagnostic {
+    packageName: string;
+    packageRoot: string;
+    srcRoot: string;
+}
+export declare function analyzeWorkspaceDocBlocks(fs: FsAdapter, workspaceRoot: string): Promise<WorkspaceDocBlockDiagnostic[]>;

package/dist/services/docs/docs-service.d.ts

@@ -13,3 +13,5 @@ export interface DocsServiceResult {
  * Generate documentation from spec files.
  */
 export declare function generateDocsFromSpecs(specFiles: string[], options: DocsServiceOptions, adapters: WorkspaceAdapters): Promise<DocsServiceResult>;
+export declare function loadAuthoredDocBlocksFromSourceFiles(sourceFiles: string[], adapters: Pick<WorkspaceAdapters, 'fs'>): Promise<DocBlock[]>;
+export declare function loadPackageAuthoredDocBlocks(packageName: string, srcRoot: string): DocBlock[];

package/dist/services/docs/docs-service.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/docs/index.d.ts

@@ -1 +1,2 @@
+export * from './docblock-audit';
 export * from './docs-service';

package/dist/services/doctor/checks/docs.d.ts

@@ -0,0 +1,3 @@
+import type { FsAdapter } from '../../../ports/fs';
+import type { CheckContext, CheckResult } from '../types';
+export declare function runDocChecks(fs: FsAdapter, ctx: CheckContext): Promise<CheckResult[]>;

package/dist/services/doctor/checks/docs.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/doctor/checks/index.d.ts

@@ -5,6 +5,7 @@ export { runAiChecks } from './ai';
 export { runCliChecks } from './cli';
 export { runConfigChecks } from './config';
 export { runDepsChecks } from './deps';
+export { runDocChecks } from './docs';
 export { runLayerChecks } from './layers';
 export { runMcpChecks } from './mcp';
 export { runWorkspaceChecks } from './workspace';

package/dist/services/doctor/doctor-service.d.ts

@@ -6,13 +6,14 @@
 import { findPackageRoot, findWorkspaceRoot, getPackageName, isMonorepo } from '../../adapters/workspace';
 import type { FsAdapter } from '../../ports/fs';
 import type { LoggerAdapter } from '../../ports/logger';
-import { runAiChecks, runCliChecks, runConfigChecks, runDepsChecks, runLayerChecks, runMcpChecks, runWorkspaceChecks } from './checks/index';
+import { runAiChecks, runCliChecks, runConfigChecks, runDepsChecks, runDocChecks, runLayerChecks, runMcpChecks, runWorkspaceChecks } from './checks/index';
 import type { CheckResult, DoctorOptions, DoctorPromptCallbacks, DoctorResult } from './types';
 interface DoctorCheckRunners {
     runCliChecks: typeof runCliChecks;
     runConfigChecks: typeof runConfigChecks;
     runMcpChecks: typeof runMcpChecks;
     runDepsChecks: typeof runDepsChecks;
+    runDocChecks: typeof runDocChecks;
     runWorkspaceChecks: typeof runWorkspaceChecks;
     runAiChecks: typeof runAiChecks;
     runLayerChecks: typeof runLayerChecks;

package/dist/services/doctor/types.d.ts

@@ -6,7 +6,7 @@
 /**
  * Categories of health checks.
  */
-export type CheckCategory = 'cli' | 'config' | 'mcp' | 'deps' | 'workspace' | 'ai' | 'layers';
+export type CheckCategory = 'cli' | 'config' | 'mcp' | 'deps' | 'docs' | 'workspace' | 'ai' | 'layers';
 /**
  * All available check categories.
  */

package/dist/services/impact/impact-detection-service.d.ts

@@ -1,13 +1,16 @@
-/**
- * Impact detection service.
- *
- * Orchestrates contract snapshot generation, diff computation,
- * and impact classification for CI/CD pipelines.
- */
 import type { FsAdapter } from '../../ports/fs';
 import type { GitAdapter } from '../../ports/git';
 import type { LoggerAdapter } from '../../ports/logger';
 import type { ImpactDetectionOptions, ImpactDetectionResult } from './types';
+export declare const ImpactDetectionRulesDocBlock: {
+    id: string;
+    title: string;
+    kind: "reference";
+    visibility: "public";
+    route: string;
+    body: string;
+    tags: string[];
+};
 /**
  * Detect the impact of contract changes between baseline and current state.
  *

package/dist/services/impact/index.d.ts

@@ -1,6 +1,12 @@
-/**
- * Impact detection service module.
- */
+export declare const ImpactDetectionOverviewDocBlock: {
+    id: string;
+    title: string;
+    kind: "goal";
+    visibility: "public";
+    route: string;
+    body: string;
+    tags: string[];
+};
 export { formatCheckRun, formatJson, formatMinimalComment, formatPrComment, } from './formatters';
 export { detectImpact } from './impact-detection-service';
 export * from './types';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/bundle.workspace",
-  "version": "4.0.3",
+  "version": "4.1.2",
   "description": "Workspace utilities for monorepo development",
   "keywords": [
     "contractspec",
@@ -33,15 +33,15 @@
   "dependencies": {
     "@ai-sdk/anthropic": "3.0.58",
     "@ai-sdk/openai": "3.0.41",
-    "@contractspec/biome-config": "3.8.2",
-    "@contractspec/lib.ai-agent": "7.0.10",
-    "@contractspec/lib.ai-providers": "3.7.8",
-    "@contractspec/lib.contracts-spec": "4.1.2",
-    "@contractspec/lib.contracts-integrations": "3.8.2",
-    "@contractspec/lib.contracts-transformers": "3.7.10",
-    "@contractspec/lib.source-extractors": "2.7.10",
-    "@contractspec/module.workspace": "4.0.3",
-    "@contractspec/lib.utils-typescript": "3.7.8",
+    "@contractspec/biome-config": "3.8.4",
+    "@contractspec/lib.ai-agent": "8.0.2",
+    "@contractspec/lib.ai-providers": "3.7.10",
+    "@contractspec/lib.contracts-spec": "5.0.2",
+    "@contractspec/lib.contracts-integrations": "3.8.6",
+    "@contractspec/lib.contracts-transformers": "3.7.14",
+    "@contractspec/lib.source-extractors": "2.7.14",
+    "@contractspec/module.workspace": "4.1.1",
+    "@contractspec/lib.utils-typescript": "3.7.10",
     "ai": "6.0.116",
     "chalk": "^5.6.2",
     "chokidar": "^5.0.0",
@@ -54,12 +54,12 @@
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@contractspec/tool.typescript": "3.7.8",
+    "@contractspec/tool.typescript": "3.7.10",
     "@types/bun": "^1.3.11",
     "@types/micromatch": "^4.0.10",
     "@types/node": "^25.3.5",
     "typescript": "^5.9.3",
-    "@contractspec/tool.bun": "3.7.8"
+    "@contractspec/tool.bun": "3.7.10"
   },
   "exports": {
     ".": {

package/dist/services/impact/impact.docblock.d.ts

@@ -1,9 +0,0 @@
-/**
- * DocBlock for Contract Impact Detection feature.
- *
- * Colocated documentation following the DocBlock pattern.
- */
-import type { DocBlock } from '@contractspec/lib.contracts-spec/docs/types';
-export declare const ImpactDetectionOverviewDoc: DocBlock;
-export declare const ImpactDetectionRulesDoc: DocBlock;
-export declare const ImpactDetectionUsageDoc: DocBlock;