@contractspec/module.workspace 4.0.0 → 4.1.0

package/dist/analysis/docblocks/diagnostics.d.ts

@@ -0,0 +1,12 @@
+export type DocBlockDiagnosticSeverity = 'error' | 'warning';
+export interface DocBlockDiagnostic {
+    ruleId: string;
+    message: string;
+    severity: DocBlockDiagnosticSeverity;
+    file: string;
+    line?: number;
+    column?: number;
+    context?: Record<string, unknown>;
+}
+export declare function isAllowedDocOwnerModule(filePath: string, sourceModule: string): boolean;
+export declare function formatDocBlockDiagnostics(diagnostics: readonly DocBlockDiagnostic[]): string;

package/dist/analysis/docblocks/evaluator.d.ts

@@ -0,0 +1,10 @@
+import type { DocBlockManifestEntry } from '@contractspec/lib.contracts-spec/docs';
+export interface ModuleDocAnalysis {
+    entries: DocBlockManifestEntry[];
+    docRefs: string[];
+    docRefExports: Array<{
+        exportName: string;
+        refs: string[];
+    }>;
+}
+export declare function extractModuleDocData(sourceText: string, filePath: string, sourceModule: string): ModuleDocAnalysis;

package/dist/analysis/docblocks/index.d.ts

@@ -0,0 +1,4 @@
+export * from './diagnostics';
+export * from './evaluator';
+export * from './list-source-files';
+export * from './manifest';

package/dist/analysis/docblocks/list-source-files.d.ts

@@ -0,0 +1,2 @@
+export declare function listSourceFiles(srcRoot: string): string[];
+export declare function toSourceModule(srcRoot: string, filePath: string): string;

package/dist/analysis/docblocks/manifest.d.ts

@@ -0,0 +1,14 @@
+import type { PackageDocManifest } from '@contractspec/lib.contracts-spec/docs';
+import { type DocBlockDiagnostic } from './diagnostics';
+export interface PackageDocAnalysisResult {
+    manifest: PackageDocManifest;
+    diagnostics: DocBlockDiagnostic[];
+}
+export declare function analyzePackageDocBlocks(options: {
+    packageName: string;
+    srcRoot: string;
+}): PackageDocAnalysisResult;
+export declare function buildPackageDocManifest(options: {
+    packageName: string;
+    srcRoot: string;
+}): PackageDocManifest;

package/dist/analysis/docblocks/static-values.d.ts

@@ -0,0 +1,6 @@
+import ts from 'typescript';
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare function evaluateExpression(expression: ts.Expression, locals: Map<string, JsonValue>, filePath: string): JsonValue | undefined;
+export declare function collectLocalValues(sourceFile: ts.SourceFile, filePath: string): Map<string, JsonValue>;

package/dist/analysis/docblocks.test.d.ts

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

package/dist/analysis/index.d.ts

@@ -3,6 +3,7 @@
  */
 export * from './deps/index';
 export * from './diff/index';
+export * from './docblocks';
 export * from './example-scan';
 export * from './feature-scan';
 export * from './grouping';

package/dist/index.js

@@ -918,6 +918,337 @@ function compareStructuralHints(diffs, a, b) {
     label: "definition section presence"
   });
 }
+// src/analysis/docblocks/diagnostics.ts
+import path from "path";
+var OWNER_SUFFIX_PATTERNS = [
+  ".feature",
+  ".command",
+  ".query",
+  ".operation",
+  ".event",
+  ".form",
+  ".view",
+  ".presentation",
+  ".capability",
+  ".dataView",
+  ".data-view",
+  ".service"
+];
+function isAllowedDocOwnerModule(filePath, sourceModule) {
+  const normalizedFilePath = filePath.replaceAll("\\", "/");
+  const normalizedSourceModule = sourceModule.replaceAll("\\", "/");
+  const baseName = path.posix.basename(normalizedSourceModule);
+  if (baseName === "index" || baseName === "spec" || baseName === "feature" || baseName === "extension") {
+    return true;
+  }
+  if (OWNER_SUFFIX_PATTERNS.some((suffix) => baseName.endsWith(suffix))) {
+    return true;
+  }
+  if (/\/(commands|queries|events|forms|views|presentations|capabilities|services)\//.test(normalizedFilePath)) {
+    return true;
+  }
+  return !/\/docs\//.test(normalizedFilePath);
+}
+function formatDocBlockDiagnostics(diagnostics) {
+  return diagnostics.map((diagnostic) => {
+    const location = diagnostic.line && diagnostic.column ? `${diagnostic.file}:${diagnostic.line}:${diagnostic.column}` : diagnostic.file;
+    return `${diagnostic.ruleId}: ${diagnostic.message} (${location})`;
+  }).join(`
+`);
+}
+// src/analysis/docblocks/evaluator.ts
+import ts2 from "typescript";
+
+// src/analysis/docblocks/static-values.ts
+import ts from "typescript";
+function evaluateExpression(expression, locals, filePath) {
+  if (ts.isParenthesizedExpression(expression)) {
+    return evaluateExpression(expression.expression, locals, filePath);
+  }
+  if (ts.isSatisfiesExpression(expression) || ts.isAsExpression(expression)) {
+    return evaluateExpression(expression.expression, locals, filePath);
+  }
+  if (ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression)) {
+    return expression.text;
+  }
+  if (ts.isNumericLiteral(expression)) {
+    return Number(expression.text);
+  }
+  if (expression.kind === ts.SyntaxKind.TrueKeyword) {
+    return true;
+  }
+  if (expression.kind === ts.SyntaxKind.FalseKeyword) {
+    return false;
+  }
+  if (expression.kind === ts.SyntaxKind.NullKeyword) {
+    return null;
+  }
+  if (ts.isArrayLiteralExpression(expression)) {
+    const values = [];
+    for (const element of expression.elements) {
+      const value = evaluateExpression(element, locals, filePath);
+      if (value === undefined) {
+        return;
+      }
+      values.push(value);
+    }
+    return values;
+  }
+  if (ts.isObjectLiteralExpression(expression)) {
+    const value = {};
+    for (const property of expression.properties) {
+      if (!ts.isPropertyAssignment(property)) {
+        return;
+      }
+      const name = property.name.getText().replace(/^["']|["']$/g, "");
+      const propertyValue = evaluateExpression(property.initializer, locals, filePath);
+      if (propertyValue === undefined) {
+        return;
+      }
+      value[name] = propertyValue;
+    }
+    return value;
+  }
+  if (ts.isIdentifier(expression)) {
+    return locals.get(expression.text);
+  }
+  if (ts.isPropertyAccessExpression(expression)) {
+    const parent = evaluateExpression(expression.expression, locals, filePath);
+    if (!parent || typeof parent !== "object" || Array.isArray(parent)) {
+      return;
+    }
+    return parent[expression.name.text];
+  }
+  if (ts.isCallExpression(expression) && ts.isIdentifier(expression.expression)) {
+    if ((expression.expression.text === "docId" || expression.expression.text === "docRef") && expression.arguments.length === 1) {
+      return evaluateExpression(expression.arguments[0], locals, filePath);
+    }
+  }
+  return;
+}
+function collectLocalValues(sourceFile, filePath) {
+  const locals = new Map;
+  for (const statement of sourceFile.statements) {
+    if (!ts.isVariableStatement(statement)) {
+      continue;
+    }
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name) || !declaration.initializer) {
+        continue;
+      }
+      const value = evaluateExpression(declaration.initializer, locals, filePath);
+      if (value !== undefined) {
+        locals.set(declaration.name.text, value);
+      }
+    }
+  }
+  return locals;
+}
+
+// src/analysis/docblocks/evaluator.ts
+function isDocBlockValue(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const candidate = value;
+  return typeof candidate.id === "string" && typeof candidate.title === "string" && typeof candidate.body === "string";
+}
+function extractDocRefsFromExpression(expression, locals, filePath) {
+  let candidate = expression;
+  while (ts2.isParenthesizedExpression(candidate) || ts2.isSatisfiesExpression(candidate) || ts2.isAsExpression(candidate)) {
+    candidate = candidate.expression;
+  }
+  if (!ts2.isObjectLiteralExpression(candidate)) {
+    return [];
+  }
+  const metaProperty = candidate.properties.find((property) => ts2.isPropertyAssignment(property) && property.name.getText() === "meta");
+  if (!metaProperty || !ts2.isPropertyAssignment(metaProperty)) {
+    return [];
+  }
+  let metaInitializer = metaProperty.initializer;
+  while (ts2.isParenthesizedExpression(metaInitializer) || ts2.isSatisfiesExpression(metaInitializer) || ts2.isAsExpression(metaInitializer)) {
+    metaInitializer = metaInitializer.expression;
+  }
+  if (!ts2.isObjectLiteralExpression(metaInitializer)) {
+    return [];
+  }
+  const docIdProperty = metaInitializer.properties.find((property) => ts2.isPropertyAssignment(property) && property.name.getText() === "docId");
+  if (!docIdProperty || !ts2.isPropertyAssignment(docIdProperty)) {
+    return [];
+  }
+  const refs = evaluateExpression(docIdProperty.initializer, locals, filePath);
+  if (!Array.isArray(refs) || !refs.every((entry) => typeof entry === "string")) {
+    throw new Error(`Non-static DocBlock reference in ${filePath} at ${docIdProperty.initializer.getStart()}`);
+  }
+  return refs;
+}
+function extractModuleDocData(sourceText, filePath, sourceModule) {
+  const sourceFile = ts2.createSourceFile(filePath, sourceText, ts2.ScriptTarget.Latest, true, ts2.ScriptKind.TS);
+  const locals = collectLocalValues(sourceFile, filePath);
+  const entries = [];
+  const docRefs = new Set;
+  const docRefExports = [];
+  for (const statement of sourceFile.statements) {
+    if (!ts2.isVariableStatement(statement)) {
+      continue;
+    }
+    const isExported = statement.modifiers?.some((modifier) => modifier.kind === ts2.SyntaxKind.ExportKeyword);
+    if (!isExported) {
+      continue;
+    }
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts2.isIdentifier(declaration.name) || !declaration.initializer) {
+        continue;
+      }
+      const value = evaluateExpression(declaration.initializer, locals, filePath);
+      const declarationRefs = extractDocRefsFromExpression(declaration.initializer, locals, filePath);
+      for (const ref of declarationRefs) {
+        docRefs.add(ref);
+      }
+      if (declarationRefs.length > 0) {
+        docRefExports.push({
+          exportName: declaration.name.text,
+          refs: declarationRefs
+        });
+      }
+      if (value === undefined) {
+        if (declaration.name.text.includes("DocBlock") || declaration.initializer.getText(sourceFile).includes("satisfies DocBlock")) {
+          throw new Error(`Non-static DocBlock source in ${filePath} at ${declaration.initializer.getStart(sourceFile)}`);
+        }
+        continue;
+      }
+      if (isDocBlockValue(value)) {
+        entries.push({
+          id: value.id,
+          exportName: declaration.name.text,
+          sourceModule,
+          block: value
+        });
+      }
+      if (Array.isArray(value) && value.every((entry) => isDocBlockValue(entry))) {
+        for (const block of value) {
+          entries.push({
+            id: block.id,
+            exportName: declaration.name.text,
+            sourceModule,
+            block
+          });
+        }
+      }
+    }
+  }
+  return { entries, docRefs: [...docRefs], docRefExports };
+}
+// src/analysis/docblocks/list-source-files.ts
+import fs from "fs";
+import path2 from "path";
+function shouldIgnoreSourceFile(filePath) {
+  return !/\.[cm]?[jt]sx?$/.test(filePath) || filePath.endsWith(".d.ts") || filePath.endsWith(".test.ts") || filePath.endsWith(".generated.ts") || filePath.includes(`${path2.sep}dist${path2.sep}`);
+}
+function listSourceFiles(srcRoot) {
+  return fs.readdirSync(srcRoot, { withFileTypes: true }).flatMap((entry) => {
+    const absolutePath = path2.join(srcRoot, entry.name);
+    if (entry.isDirectory()) {
+      return listSourceFiles(absolutePath);
+    }
+    return shouldIgnoreSourceFile(absolutePath) ? [] : [absolutePath];
+  }).sort((left, right) => left.localeCompare(right));
+}
+function toSourceModule(srcRoot, filePath) {
+  return path2.relative(srcRoot, filePath).replace(/\\/g, "/").replace(/\.[cm]?[jt]sx?$/, "");
+}
+// src/analysis/docblocks/manifest.ts
+import fs2 from "fs";
+function createDiagnostic(ruleId, message, file, context) {
+  return {
+    ruleId,
+    message,
+    severity: "error",
+    file,
+    context
+  };
+}
+function analyzePackageDocBlocks(options) {
+  const { packageName, srcRoot } = options;
+  const diagnostics = [];
+  const entries = [];
+  const seenIds = new Map;
+  const seenRoutes = new Map;
+  const moduleRecords = new Map;
+  for (const filePath of listSourceFiles(srcRoot)) {
+    if (filePath.endsWith(".docblock.ts")) {
+      diagnostics.push(createDiagnostic("docblock-standalone-source", "Standalone DocBlock sources are not allowed.", filePath));
+    }
+    if (filePath.includes("/docs/tech/") || filePath.includes("\\docs\\tech\\")) {
+      diagnostics.push(createDiagnostic("docblock-tech-folder", "docs/tech source files are not allowed.", filePath));
+    }
+    const sourceModule = toSourceModule(srcRoot, filePath);
+    try {
+      const moduleData = extractModuleDocData(fs2.readFileSync(filePath, "utf8"), filePath, sourceModule);
+      moduleRecords.set(sourceModule, {
+        entries: moduleData.entries,
+        docRefExports: moduleData.docRefExports,
+        filePath,
+        sourceModule
+      });
+      if (moduleData.entries.length > 0 && !isAllowedDocOwnerModule(filePath, sourceModule)) {
+        diagnostics.push(createDiagnostic("docblock-orphan-owner", "DocBlocks must be exported from the owner module, not a docs-only helper file.", filePath, { sourceModule }));
+      }
+      for (const entry of moduleData.entries) {
+        const sourceRef = `${entry.sourceModule}:${entry.exportName}`;
+        const priorId = seenIds.get(entry.id);
+        if (priorId) {
+          diagnostics.push(createDiagnostic("docblock-duplicate-id", `Duplicate DocBlock id ${entry.id} in ${sourceRef} and ${priorId}.`, filePath, { docId: entry.id, prior: priorId, sourceRef }));
+        } else {
+          seenIds.set(entry.id, sourceRef);
+        }
+        if (entry.block.route) {
+          const priorRoute = seenRoutes.get(entry.block.route);
+          if (priorRoute) {
+            diagnostics.push(createDiagnostic("docblock-duplicate-route", `Duplicate DocBlock route ${entry.block.route} in ${sourceRef} and ${priorRoute}.`, filePath, { route: entry.block.route, prior: priorRoute, sourceRef }));
+          } else {
+            seenRoutes.set(entry.block.route, sourceRef);
+          }
+        }
+        entries.push(entry);
+      }
+    } catch (error) {
+      diagnostics.push(createDiagnostic("docblock-non-static-source", error instanceof Error ? error.message : `Non-static DocBlock source in ${filePath}.`, filePath));
+    }
+  }
+  for (const record of moduleRecords.values()) {
+    const localIds = new Set(record.entries.map((entry) => entry.id));
+    for (const docRefExport of record.docRefExports) {
+      for (const ref of docRefExport.refs) {
+        if (localIds.has(ref)) {
+          continue;
+        }
+        if (seenIds.has(ref)) {
+          diagnostics.push(createDiagnostic("docblock-cross-file-reference", `${docRefExport.exportName} references DocBlock ${ref}, but the DocBlock is not exported from the same module.`, record.filePath, { docId: ref, exportName: docRefExport.exportName }));
+          continue;
+        }
+        diagnostics.push(createDiagnostic("docblock-missing-ref", `${docRefExport.exportName} references missing DocBlock ${ref}.`, record.filePath, { docId: ref, exportName: docRefExport.exportName }));
+      }
+    }
+  }
+  entries.sort((left, right) => left.id.localeCompare(right.id));
+  return {
+    manifest: {
+      packageName,
+      generatedAt: new Date().toISOString(),
+      blocks: entries
+    },
+    diagnostics
+  };
+}
+function buildPackageDocManifest(options) {
+  const analysis = analyzePackageDocBlocks(options);
+  const failures = analysis.diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+  if (failures.length > 0) {
+    throw new Error(formatDocBlockDiagnostics(failures));
+  }
+  return analysis.manifest;
+}
 // src/analysis/example-scan.ts
 function isExampleFile(filePath) {
   return filePath.includes("/example.") || filePath.endsWith(".example.ts");
@@ -1694,8 +2025,8 @@ function sortFields(fields) {
 // src/analysis/snapshot/snapshot.ts
 function generateSnapshot(specs, options = {}) {
   const snapshots = [];
-  for (const { path, content } of specs) {
-    const scanned = scanSpecSource(content, path);
+  for (const { path: path3, content } of specs) {
+    const scanned = scanSpecSource(content, path3);
     if (options.types && !options.types.includes(scanned.specType)) {
       continue;
     }
@@ -2657,7 +2988,7 @@ async function formatFilesBatch(files, config, options, logger) {
   return formatFiles(files, config, options, logger);
 }
 // src/formatters/spec-markdown.ts
-import * as path from "path";
+import * as path3 from "path";
 function specToMarkdown(spec, format, optionsOrDepth = 0) {
   const options = typeof optionsOrDepth === "number" ? { depth: optionsOrDepth } : optionsOrDepth;
   const depth = options.depth ?? 0;
@@ -2782,7 +3113,7 @@ function formatFullMode(spec, lines, indent, rootPath) {
     lines.push(`${indent}- **Tags**: ${spec.meta.tags.join(", ")}`);
   }
   if (spec.filePath) {
-    const displayPath = rootPath ? path.relative(rootPath, spec.filePath) : spec.filePath;
+    const displayPath = rootPath ? path3.relative(rootPath, spec.filePath) : spec.filePath;
     lines.push(`${indent}- **File**: \`${displayPath}\``);
   }
   lines.push("");
@@ -4191,6 +4522,7 @@ export const ${runnerName} = new WorkflowRunner({
 }
 export {
   validateSpecStructure,
+  toSourceModule,
   toPascalCase,
   toKebabCase,
   toDot,
@@ -4207,9 +4539,11 @@ export {
   parseImportedSpecNames,
   normalizeValue,
   loadSpecFromSource,
+  listSourceFiles,
   isFeatureFile,
   isExampleFile,
   isBreakingChange,
+  isAllowedDocOwnerModule,
   inferSpecTypeFromFilePath,
   inferSpecTypeFromCodeBlock,
   groupSpecsToArray,
@@ -4239,12 +4573,14 @@ export {
   generateAppBlueprintSpec,
   formatFilesBatch,
   formatFiles,
+  formatDocBlockDiagnostics,
   findMissingDependencies,
   findMatchingRule,
   filterSpecs,
   filterFeatures,
   extractTestTarget,
   extractTestCoverage,
+  extractModuleDocData,
   escapeString,
   detectFormatter,
   detectCycles,
@@ -4261,11 +4597,13 @@ export {
   buildTestPrompt,
   buildReverseEdges,
   buildPresentationSpecPrompt,
+  buildPackageDocManifest,
   buildOperationSpecPrompt,
   buildHandlerPrompt,
   buildFormPrompt,
   buildEventSpecPrompt,
   buildComponentPrompt,
+  analyzePackageDocBlocks,
   addExampleContext,
   addContractNode,
   SpecGroupingStrategies,

package/dist/node/index.js

@@ -917,6 +917,337 @@ function compareStructuralHints(diffs, a, b) {
     label: "definition section presence"
   });
 }
+// src/analysis/docblocks/diagnostics.ts
+import path from "node:path";
+var OWNER_SUFFIX_PATTERNS = [
+  ".feature",
+  ".command",
+  ".query",
+  ".operation",
+  ".event",
+  ".form",
+  ".view",
+  ".presentation",
+  ".capability",
+  ".dataView",
+  ".data-view",
+  ".service"
+];
+function isAllowedDocOwnerModule(filePath, sourceModule) {
+  const normalizedFilePath = filePath.replaceAll("\\", "/");
+  const normalizedSourceModule = sourceModule.replaceAll("\\", "/");
+  const baseName = path.posix.basename(normalizedSourceModule);
+  if (baseName === "index" || baseName === "spec" || baseName === "feature" || baseName === "extension") {
+    return true;
+  }
+  if (OWNER_SUFFIX_PATTERNS.some((suffix) => baseName.endsWith(suffix))) {
+    return true;
+  }
+  if (/\/(commands|queries|events|forms|views|presentations|capabilities|services)\//.test(normalizedFilePath)) {
+    return true;
+  }
+  return !/\/docs\//.test(normalizedFilePath);
+}
+function formatDocBlockDiagnostics(diagnostics) {
+  return diagnostics.map((diagnostic) => {
+    const location = diagnostic.line && diagnostic.column ? `${diagnostic.file}:${diagnostic.line}:${diagnostic.column}` : diagnostic.file;
+    return `${diagnostic.ruleId}: ${diagnostic.message} (${location})`;
+  }).join(`
+`);
+}
+// src/analysis/docblocks/evaluator.ts
+import ts2 from "typescript";
+
+// src/analysis/docblocks/static-values.ts
+import ts from "typescript";
+function evaluateExpression(expression, locals, filePath) {
+  if (ts.isParenthesizedExpression(expression)) {
+    return evaluateExpression(expression.expression, locals, filePath);
+  }
+  if (ts.isSatisfiesExpression(expression) || ts.isAsExpression(expression)) {
+    return evaluateExpression(expression.expression, locals, filePath);
+  }
+  if (ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression)) {
+    return expression.text;
+  }
+  if (ts.isNumericLiteral(expression)) {
+    return Number(expression.text);
+  }
+  if (expression.kind === ts.SyntaxKind.TrueKeyword) {
+    return true;
+  }
+  if (expression.kind === ts.SyntaxKind.FalseKeyword) {
+    return false;
+  }
+  if (expression.kind === ts.SyntaxKind.NullKeyword) {
+    return null;
+  }
+  if (ts.isArrayLiteralExpression(expression)) {
+    const values = [];
+    for (const element of expression.elements) {
+      const value = evaluateExpression(element, locals, filePath);
+      if (value === undefined) {
+        return;
+      }
+      values.push(value);
+    }
+    return values;
+  }
+  if (ts.isObjectLiteralExpression(expression)) {
+    const value = {};
+    for (const property of expression.properties) {
+      if (!ts.isPropertyAssignment(property)) {
+        return;
+      }
+      const name = property.name.getText().replace(/^["']|["']$/g, "");
+      const propertyValue = evaluateExpression(property.initializer, locals, filePath);
+      if (propertyValue === undefined) {
+        return;
+      }
+      value[name] = propertyValue;
+    }
+    return value;
+  }
+  if (ts.isIdentifier(expression)) {
+    return locals.get(expression.text);
+  }
+  if (ts.isPropertyAccessExpression(expression)) {
+    const parent = evaluateExpression(expression.expression, locals, filePath);
+    if (!parent || typeof parent !== "object" || Array.isArray(parent)) {
+      return;
+    }
+    return parent[expression.name.text];
+  }
+  if (ts.isCallExpression(expression) && ts.isIdentifier(expression.expression)) {
+    if ((expression.expression.text === "docId" || expression.expression.text === "docRef") && expression.arguments.length === 1) {
+      return evaluateExpression(expression.arguments[0], locals, filePath);
+    }
+  }
+  return;
+}
+function collectLocalValues(sourceFile, filePath) {
+  const locals = new Map;
+  for (const statement of sourceFile.statements) {
+    if (!ts.isVariableStatement(statement)) {
+      continue;
+    }
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name) || !declaration.initializer) {
+        continue;
+      }
+      const value = evaluateExpression(declaration.initializer, locals, filePath);
+      if (value !== undefined) {
+        locals.set(declaration.name.text, value);
+      }
+    }
+  }
+  return locals;
+}
+
+// src/analysis/docblocks/evaluator.ts
+function isDocBlockValue(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const candidate = value;
+  return typeof candidate.id === "string" && typeof candidate.title === "string" && typeof candidate.body === "string";
+}
+function extractDocRefsFromExpression(expression, locals, filePath) {
+  let candidate = expression;
+  while (ts2.isParenthesizedExpression(candidate) || ts2.isSatisfiesExpression(candidate) || ts2.isAsExpression(candidate)) {
+    candidate = candidate.expression;
+  }
+  if (!ts2.isObjectLiteralExpression(candidate)) {
+    return [];
+  }
+  const metaProperty = candidate.properties.find((property) => ts2.isPropertyAssignment(property) && property.name.getText() === "meta");
+  if (!metaProperty || !ts2.isPropertyAssignment(metaProperty)) {
+    return [];
+  }
+  let metaInitializer = metaProperty.initializer;
+  while (ts2.isParenthesizedExpression(metaInitializer) || ts2.isSatisfiesExpression(metaInitializer) || ts2.isAsExpression(metaInitializer)) {
+    metaInitializer = metaInitializer.expression;
+  }
+  if (!ts2.isObjectLiteralExpression(metaInitializer)) {
+    return [];
+  }
+  const docIdProperty = metaInitializer.properties.find((property) => ts2.isPropertyAssignment(property) && property.name.getText() === "docId");
+  if (!docIdProperty || !ts2.isPropertyAssignment(docIdProperty)) {
+    return [];
+  }
+  const refs = evaluateExpression(docIdProperty.initializer, locals, filePath);
+  if (!Array.isArray(refs) || !refs.every((entry) => typeof entry === "string")) {
+    throw new Error(`Non-static DocBlock reference in ${filePath} at ${docIdProperty.initializer.getStart()}`);
+  }
+  return refs;
+}
+function extractModuleDocData(sourceText, filePath, sourceModule) {
+  const sourceFile = ts2.createSourceFile(filePath, sourceText, ts2.ScriptTarget.Latest, true, ts2.ScriptKind.TS);
+  const locals = collectLocalValues(sourceFile, filePath);
+  const entries = [];
+  const docRefs = new Set;
+  const docRefExports = [];
+  for (const statement of sourceFile.statements) {
+    if (!ts2.isVariableStatement(statement)) {
+      continue;
+    }
+    const isExported = statement.modifiers?.some((modifier) => modifier.kind === ts2.SyntaxKind.ExportKeyword);
+    if (!isExported) {
+      continue;
+    }
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts2.isIdentifier(declaration.name) || !declaration.initializer) {
+        continue;
+      }
+      const value = evaluateExpression(declaration.initializer, locals, filePath);
+      const declarationRefs = extractDocRefsFromExpression(declaration.initializer, locals, filePath);
+      for (const ref of declarationRefs) {
+        docRefs.add(ref);
+      }
+      if (declarationRefs.length > 0) {
+        docRefExports.push({
+          exportName: declaration.name.text,
+          refs: declarationRefs
+        });
+      }
+      if (value === undefined) {
+        if (declaration.name.text.includes("DocBlock") || declaration.initializer.getText(sourceFile).includes("satisfies DocBlock")) {
+          throw new Error(`Non-static DocBlock source in ${filePath} at ${declaration.initializer.getStart(sourceFile)}`);
+        }
+        continue;
+      }
+      if (isDocBlockValue(value)) {
+        entries.push({
+          id: value.id,
+          exportName: declaration.name.text,
+          sourceModule,
+          block: value
+        });
+      }
+      if (Array.isArray(value) && value.every((entry) => isDocBlockValue(entry))) {
+        for (const block of value) {
+          entries.push({
+            id: block.id,
+            exportName: declaration.name.text,
+            sourceModule,
+            block
+          });
+        }
+      }
+    }
+  }
+  return { entries, docRefs: [...docRefs], docRefExports };
+}
+// src/analysis/docblocks/list-source-files.ts
+import fs from "node:fs";
+import path2 from "node:path";
+function shouldIgnoreSourceFile(filePath) {
+  return !/\.[cm]?[jt]sx?$/.test(filePath) || filePath.endsWith(".d.ts") || filePath.endsWith(".test.ts") || filePath.endsWith(".generated.ts") || filePath.includes(`${path2.sep}dist${path2.sep}`);
+}
+function listSourceFiles(srcRoot) {
+  return fs.readdirSync(srcRoot, { withFileTypes: true }).flatMap((entry) => {
+    const absolutePath = path2.join(srcRoot, entry.name);
+    if (entry.isDirectory()) {
+      return listSourceFiles(absolutePath);
+    }
+    return shouldIgnoreSourceFile(absolutePath) ? [] : [absolutePath];
+  }).sort((left, right) => left.localeCompare(right));
+}
+function toSourceModule(srcRoot, filePath) {
+  return path2.relative(srcRoot, filePath).replace(/\\/g, "/").replace(/\.[cm]?[jt]sx?$/, "");
+}
+// src/analysis/docblocks/manifest.ts
+import fs2 from "node:fs";
+function createDiagnostic(ruleId, message, file, context) {
+  return {
+    ruleId,
+    message,
+    severity: "error",
+    file,
+    context
+  };
+}
+function analyzePackageDocBlocks(options) {
+  const { packageName, srcRoot } = options;
+  const diagnostics = [];
+  const entries = [];
+  const seenIds = new Map;
+  const seenRoutes = new Map;
+  const moduleRecords = new Map;
+  for (const filePath of listSourceFiles(srcRoot)) {
+    if (filePath.endsWith(".docblock.ts")) {
+      diagnostics.push(createDiagnostic("docblock-standalone-source", "Standalone DocBlock sources are not allowed.", filePath));
+    }
+    if (filePath.includes("/docs/tech/") || filePath.includes("\\docs\\tech\\")) {
+      diagnostics.push(createDiagnostic("docblock-tech-folder", "docs/tech source files are not allowed.", filePath));
+    }
+    const sourceModule = toSourceModule(srcRoot, filePath);
+    try {
+      const moduleData = extractModuleDocData(fs2.readFileSync(filePath, "utf8"), filePath, sourceModule);
+      moduleRecords.set(sourceModule, {
+        entries: moduleData.entries,
+        docRefExports: moduleData.docRefExports,
+        filePath,
+        sourceModule
+      });
+      if (moduleData.entries.length > 0 && !isAllowedDocOwnerModule(filePath, sourceModule)) {
+        diagnostics.push(createDiagnostic("docblock-orphan-owner", "DocBlocks must be exported from the owner module, not a docs-only helper file.", filePath, { sourceModule }));
+      }
+      for (const entry of moduleData.entries) {
+        const sourceRef = `${entry.sourceModule}:${entry.exportName}`;
+        const priorId = seenIds.get(entry.id);
+        if (priorId) {
+          diagnostics.push(createDiagnostic("docblock-duplicate-id", `Duplicate DocBlock id ${entry.id} in ${sourceRef} and ${priorId}.`, filePath, { docId: entry.id, prior: priorId, sourceRef }));
+        } else {
+          seenIds.set(entry.id, sourceRef);
+        }
+        if (entry.block.route) {
+          const priorRoute = seenRoutes.get(entry.block.route);
+          if (priorRoute) {
+            diagnostics.push(createDiagnostic("docblock-duplicate-route", `Duplicate DocBlock route ${entry.block.route} in ${sourceRef} and ${priorRoute}.`, filePath, { route: entry.block.route, prior: priorRoute, sourceRef }));
+          } else {
+            seenRoutes.set(entry.block.route, sourceRef);
+          }
+        }
+        entries.push(entry);
+      }
+    } catch (error) {
+      diagnostics.push(createDiagnostic("docblock-non-static-source", error instanceof Error ? error.message : `Non-static DocBlock source in ${filePath}.`, filePath));
+    }
+  }
+  for (const record of moduleRecords.values()) {
+    const localIds = new Set(record.entries.map((entry) => entry.id));
+    for (const docRefExport of record.docRefExports) {
+      for (const ref of docRefExport.refs) {
+        if (localIds.has(ref)) {
+          continue;
+        }
+        if (seenIds.has(ref)) {
+          diagnostics.push(createDiagnostic("docblock-cross-file-reference", `${docRefExport.exportName} references DocBlock ${ref}, but the DocBlock is not exported from the same module.`, record.filePath, { docId: ref, exportName: docRefExport.exportName }));
+          continue;
+        }
+        diagnostics.push(createDiagnostic("docblock-missing-ref", `${docRefExport.exportName} references missing DocBlock ${ref}.`, record.filePath, { docId: ref, exportName: docRefExport.exportName }));
+      }
+    }
+  }
+  entries.sort((left, right) => left.id.localeCompare(right.id));
+  return {
+    manifest: {
+      packageName,
+      generatedAt: new Date().toISOString(),
+      blocks: entries
+    },
+    diagnostics
+  };
+}
+function buildPackageDocManifest(options) {
+  const analysis = analyzePackageDocBlocks(options);
+  const failures = analysis.diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+  if (failures.length > 0) {
+    throw new Error(formatDocBlockDiagnostics(failures));
+  }
+  return analysis.manifest;
+}
 // src/analysis/example-scan.ts
 function isExampleFile(filePath) {
   return filePath.includes("/example.") || filePath.endsWith(".example.ts");
@@ -1693,8 +2024,8 @@ function sortFields(fields) {
 // src/analysis/snapshot/snapshot.ts
 function generateSnapshot(specs, options = {}) {
   const snapshots = [];
-  for (const { path, content } of specs) {
-    const scanned = scanSpecSource(content, path);
+  for (const { path: path3, content } of specs) {
+    const scanned = scanSpecSource(content, path3);
     if (options.types && !options.types.includes(scanned.specType)) {
       continue;
     }
@@ -2656,7 +2987,7 @@ async function formatFilesBatch(files, config, options, logger) {
   return formatFiles(files, config, options, logger);
 }
 // src/formatters/spec-markdown.ts
-import * as path from "node:path";
+import * as path3 from "node:path";
 function specToMarkdown(spec, format, optionsOrDepth = 0) {
   const options = typeof optionsOrDepth === "number" ? { depth: optionsOrDepth } : optionsOrDepth;
   const depth = options.depth ?? 0;
@@ -2781,7 +3112,7 @@ function formatFullMode(spec, lines, indent, rootPath) {
     lines.push(`${indent}- **Tags**: ${spec.meta.tags.join(", ")}`);
   }
   if (spec.filePath) {
-    const displayPath = rootPath ? path.relative(rootPath, spec.filePath) : spec.filePath;
+    const displayPath = rootPath ? path3.relative(rootPath, spec.filePath) : spec.filePath;
     lines.push(`${indent}- **File**: \`${displayPath}\``);
   }
   lines.push("");
@@ -4190,6 +4521,7 @@ export const ${runnerName} = new WorkflowRunner({
 }
 export {
   validateSpecStructure,
+  toSourceModule,
   toPascalCase,
   toKebabCase,
   toDot,
@@ -4206,9 +4538,11 @@ export {
   parseImportedSpecNames,
   normalizeValue,
   loadSpecFromSource,
+  listSourceFiles,
   isFeatureFile,
   isExampleFile,
   isBreakingChange,
+  isAllowedDocOwnerModule,
   inferSpecTypeFromFilePath,
   inferSpecTypeFromCodeBlock,
   groupSpecsToArray,
@@ -4238,12 +4572,14 @@ export {
   generateAppBlueprintSpec,
   formatFilesBatch,
   formatFiles,
+  formatDocBlockDiagnostics,
   findMissingDependencies,
   findMatchingRule,
   filterSpecs,
   filterFeatures,
   extractTestTarget,
   extractTestCoverage,
+  extractModuleDocData,
   escapeString,
   detectFormatter,
   detectCycles,
@@ -4260,11 +4596,13 @@ export {
   buildTestPrompt,
   buildReverseEdges,
   buildPresentationSpecPrompt,
+  buildPackageDocManifest,
   buildOperationSpecPrompt,
   buildHandlerPrompt,
   buildFormPrompt,
   buildEventSpecPrompt,
   buildComponentPrompt,
+  analyzePackageDocBlocks,
   addExampleContext,
   addContractNode,
   SpecGroupingStrategies,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/module.workspace",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Workspace discovery and management module",
   "keywords": [
     "contractspec",
@@ -31,17 +31,17 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@contractspec/lib.contracts-spec": "4.0.0",
-    "@contractspec/lib.schema": "3.7.6",
+    "@contractspec/lib.contracts-spec": "5.0.0",
+    "@contractspec/lib.schema": "3.7.10",
+    "typescript": "^5.9.3",
     "compare-versions": "^6.1.1",
     "ts-morph": "^27.0.2",
     "zod": "^4.3.5",
-    "@contractspec/lib.contracts-integrations": "3.7.7"
+    "@contractspec/lib.contracts-integrations": "3.8.4"
   },
   "devDependencies": {
-    "@contractspec/tool.typescript": "3.7.6",
-    "typescript": "^5.9.3",
-    "@contractspec/tool.bun": "3.7.6"
+    "@contractspec/tool.typescript": "3.7.9",
+    "@contractspec/tool.bun": "3.7.9"
   },
   "exports": {
     ".": {