@wildo-ai/saas-technical-doc 1.1.2 → 1.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wildo-ai/saas-technical-doc",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Generated-application technical documentation engine — application-consumer content, verified OpenAPI projection, rendering, publication validation, and the lightweight browser runtime used by documentation portals.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Wildo AI",
@@ -50,10 +50,11 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@wildo-ai/platform-config-lib": "1.1.2",
-    "@wildo-ai/saas-models": "1.1.2",
-    "@wildo-ai/saas-specifications": "1.1.2",
-    "@wildo-ai/zod-decorators": "1.1.2",
+    "@wildo-ai/external-connectors-public": "1.1.4",
+    "@wildo-ai/platform-config-lib": "1.1.4",
+    "@wildo-ai/saas-models": "1.1.4",
+    "@wildo-ai/saas-specifications": "1.1.4",
+    "@wildo-ai/zod-decorators": "1.1.4",
     "yaml": "^2.3.4",
     "zod": "4.3.6"
   },

package/dist/esm/companion/rendering/technical-documentation-markdown-renderer.d.ts

@@ -1,9 +0,0 @@
-import { type TechnicalDocumentationApiReferenceTargetV1, type TechnicalDocumentationResolvedAssetBundleManifestV1 } from '@wildo-ai/saas-specifications/technical-documentation';
-import { type TechnicalDocumentationRenderModel, type TechnicalDocumentationRendererResult } from './technical-documentation-render-model';
-export declare function renderTechnicalDocumentationMarkdown(input: {
-    readonly model: TechnicalDocumentationRenderModel;
-    readonly resolvedAssetBundle: TechnicalDocumentationResolvedAssetBundleManifestV1;
-    readonly assetBytesByPath: ReadonlyMap<string, Uint8Array>;
-    readonly resolveApiReferenceTarget?: (target: TechnicalDocumentationApiReferenceTargetV1) => string;
-}): TechnicalDocumentationRendererResult;
-//# sourceMappingURL=technical-documentation-markdown-renderer.d.ts.map

package/dist/esm/companion/rendering/technical-documentation-markdown-renderer.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"technical-documentation-markdown-renderer.d.ts","sourceRoot":"","sources":["../../../../../src/companion/rendering/technical-documentation-markdown-renderer.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,0CAA0C,EAC/C,KAAK,mDAAmD,EAEzD,MAAM,uDAAuD,CAAC;AAG/D,OAAO,EAEL,KAAK,iCAAiC,EACtC,KAAK,oCAAoC,EAE1C,MAAM,wCAAwC,CAAC;AA+DhD,wBAAgB,oCAAoC,CAAC,KAAK,EAAE;IAC1D,QAAQ,CAAC,KAAK,EAAE,iCAAiC,CAAC;IAClD,QAAQ,CAAC,mBAAmB,EAAE,mDAAmD,CAAC;IAClF,QAAQ,CAAC,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAC3D,QAAQ,CAAC,yBAAyB,CAAC,EAAE,CAAC,MAAM,EAAE,0CAA0C,KAAK,MAAM,CAAC;CACrG,GAAG,oCAAoC,CAkDvC"}

package/dist/esm/companion/rendering/technical-documentation-markdown-renderer.js

@@ -1,111 +0,0 @@
-import { TechnicalDocumentationAssetResolutionStatus, TechnicalDocumentationLinkKind, TechnicalDocumentationOutputKind, TechnicalDocumentationRendererKind, } from '@wildo-ai/saas-specifications/technical-documentation';
-import { isImplicitLeadSection, pruneUnpublishedSiteLinks } from './technical-documentation-markdown-links.js';
-import { createTechnicalDocumentationRendererExecution, ENGINE_UNIT_ROUTES, } from './technical-documentation-render-model.js';
-import { technicalDocumentationAssetFileStem, } from '../technical-documentation-asset-path.js';
-/**
- * Statuses whose asset carries real bytes at a real path, and therefore renders.
- *
- * `PLACEHOLDER` belongs here with `RESOLVED`: the framework materializes a stand-in image,
- * so the page shows a picture rather than a hole. That is the whole distinction from
- * `MISSING` — both mean "the real capture has not run", but only one of them SHIPS
- * something. Rendering is a question about bytes; whether provisional imagery may be
- * published at all is an environment policy decided at publication, not here.
- */
-const RENDERABLE_ASSET_STATUSES = new Set([
-    TechnicalDocumentationAssetResolutionStatus.PLACEHOLDER,
-    TechnicalDocumentationAssetResolutionStatus.RESOLVED,
-]);
-const MARKDOWN_RENDERER_REF = 'technical-documentation:renderer/markdown';
-function relativeMarkdownPath(sourcePath, targetPath) {
-    const relativePath = path.relative(path.dirname(sourcePath), targetPath);
-    return relativePath.startsWith('.') ? relativePath : `./${relativePath}`;
-}
-function renderLink(link, model, sourcePath, resolveApiReferenceTarget) {
-    if (link.kind === TechnicalDocumentationLinkKind.UNIT) {
-        const targetPath = model.unitPathByRef.get(link.targetUnitRef);
-        if (targetPath === undefined)
-            throw new Error(`technical-documentation link target is not in the authorized render model: ${link.targetUnitRef}`);
-        return `- [${link.label}](${relativeMarkdownPath(sourcePath, `markdown/${targetPath}.md`)})`;
-    }
-    if (link.kind === TechnicalDocumentationLinkKind.EXTERNAL)
-        return `- [${link.label}](${link.externalUrl})`;
-    if (link.kind === TechnicalDocumentationLinkKind.API_REFERENCE) {
-        if (resolveApiReferenceTarget === undefined)
-            throw new Error(`technical-documentation API-reference link was not resolved before Markdown rendering: ${link.linkRef}`);
-        return `- [${link.label}](${resolveApiReferenceTarget(link.apiReferenceTarget)})`;
-    }
-    return `- ${link.label}`;
-}
-function renderUnit(unit, model, assetPathByRef, resolveApiReferenceTarget) {
-    const unitPath = model.unitPathByRef.get(unit.unitRef);
-    if (unitPath === undefined)
-        throw new Error(`technical-documentation render model has no path for ${unit.unitRef}`);
-    const sourcePath = `markdown/${unitPath}.md`;
-    const publishedPaths = new Set(model.unitPathByRef.values());
-    const sections = unit.sections.map((section, index) => {
-        const body = pruneUnpublishedSiteLinks(section.bodyMarkdown, publishedPaths, ENGINE_UNIT_ROUTES);
-        return isImplicitLeadSection(section, index) ? body : `## ${section.heading}\n\n${body}`;
-    }).join('\n\n');
-    const links = unit.links.length === 0 ? '' : `\n\n## Related\n\n${unit.links.map((link) => renderLink(link, model, sourcePath, resolveApiReferenceTarget)).join('\n')}`;
-    const figures = unit.assetRequests.flatMap((request) => {
-        const assetPath = assetPathByRef.get(request.assetRef);
-        return assetPath === undefined ? [] : [`![${request.altText}](${relativeMarkdownPath(sourcePath, assetPath)})`];
-    });
-    const assetSection = figures.length === 0 ? '' : `\n\n## Product view\n\n${figures.join('\n\n')}`;
-    return `# ${unit.title}\n\n${unit.summary}\n\n${sections}${assetSection}${links}\n`;
-}
-export function renderTechnicalDocumentationMarkdown(input) {
-    const assetPathByRef = new Map(input.resolvedAssetBundle.resolvedAssetSet.assets.flatMap((asset) => RENDERABLE_ASSET_STATUSES.has(asset.status) ? [[asset.assetRef, asset.normalizedRelativePath]] : []));
-    const sourceUnitRefsByAssetRef = new Map();
-    for (const unit of input.model.units) {
-        for (const request of unit.assetRequests) {
-            const owners = sourceUnitRefsByAssetRef.get(request.assetRef) ?? [];
-            owners.push(unit.unitRef);
-            sourceUnitRefsByAssetRef.set(request.assetRef, owners);
-        }
-    }
-    const assetFiles = input.resolvedAssetBundle.resolvedAssetSet.assets.flatMap((asset) => {
-        if (!RENDERABLE_ASSET_STATUSES.has(asset.status))
-            return [];
-        const path = asset.normalizedRelativePath;
-        const bytes = input.assetBytesByPath.get(path);
-        if (bytes === undefined)
-            throw new Error(`technical-documentation Markdown asset bytes are absent: ${path}`);
-        const sourceUnitRefs = [...(sourceUnitRefsByAssetRef.get(asset.assetRef) ?? [])].sort();
-        if (sourceUnitRefs.length === 0)
-            throw new Error(`technical-documentation resolved asset has no authorized unit owner: ${asset.assetRef}`);
-        return [{
-                outputRef: `technical-documentation:output/markdown-asset/${technicalDocumentationAssetFileStem(asset.assetRef)}`,
-                rendererRef: MARKDOWN_RENDERER_REF,
-                outputKind: TechnicalDocumentationOutputKind.ASSET,
-                sourceUnitRefs,
-                normalizedRelativePath: path,
-                mediaType: asset.mediaType,
-                bytes,
-            }];
-    });
-    return {
-        execution: createTechnicalDocumentationRendererExecution({
-            rendererKind: TechnicalDocumentationRendererKind.MARKDOWN,
-            rendererRef: MARKDOWN_RENDERER_REF,
-            rendererVersion: 1,
-            configurationRef: 'technical-documentation:renderer-configuration/markdown-v1',
-        }),
-        files: [...input.model.units.map((unit) => {
-                const path = input.model.unitPathByRef.get(unit.unitRef);
-                return {
-                    // Keep the complete route identity: final path segments are not a
-                    // globally unique page identity once consumer documentation has domains.
-                    outputRef: `technical-documentation:output/markdown/${path.split('/').join(':')}`,
-                    rendererRef: MARKDOWN_RENDERER_REF,
-                    outputKind: TechnicalDocumentationOutputKind.MARKDOWN_DOCUMENT,
-                    sourceUnitRefs: [unit.unitRef],
-                    normalizedRelativePath: `markdown/${path}.md`,
-                    mediaType: 'text/markdown',
-                    bytes: Buffer.from(renderUnit(unit, input.model, assetPathByRef, input.resolveApiReferenceTarget), 'utf8'),
-                };
-            }), ...assetFiles],
-    };
-}
-import { posix as path } from 'node:path';
-//# sourceMappingURL=technical-documentation-markdown-renderer.js.map

package/dist/esm/companion/rendering/technical-documentation-markdown-renderer.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"technical-documentation-markdown-renderer.js","sourceRoot":"","sources":["../../../../../src/companion/rendering/technical-documentation-markdown-renderer.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  TechnicalDocumentationAssetResolutionStatus,\n  TechnicalDocumentationLinkKind,\n  TechnicalDocumentationOutputKind,\n  TechnicalDocumentationRendererKind,\n  type TechnicalDocumentationLinkV1,\n  type TechnicalDocumentationApiReferenceTargetV1,\n  type TechnicalDocumentationResolvedAssetBundleManifestV1,\n  type TechnicalDocumentationUnitV1,\n} from '@wildo-ai/saas-specifications/technical-documentation';\nimport { isImplicitLeadSection, pruneUnpublishedSiteLinks } from './technical-documentation-markdown-links';\n\nimport {\n  createTechnicalDocumentationRendererExecution,\n  type TechnicalDocumentationRenderModel,\n  type TechnicalDocumentationRendererResult,\n  ENGINE_UNIT_ROUTES,\n} from './technical-documentation-render-model';\nimport {\n  technicalDocumentationAssetFileStem,\n} from '../technical-documentation-asset-path';\n\n/**\n * Statuses whose asset carries real bytes at a real path, and therefore renders.\n *\n * `PLACEHOLDER` belongs here with `RESOLVED`: the framework materializes a stand-in image,\n * so the page shows a picture rather than a hole. That is the whole distinction from\n * `MISSING` — both mean \"the real capture has not run\", but only one of them SHIPS\n * something. Rendering is a question about bytes; whether provisional imagery may be\n * published at all is an environment policy decided at publication, not here.\n */\nconst RENDERABLE_ASSET_STATUSES: ReadonlySet<TechnicalDocumentationAssetResolutionStatus> = new Set([\n  TechnicalDocumentationAssetResolutionStatus.PLACEHOLDER,\n  TechnicalDocumentationAssetResolutionStatus.RESOLVED,\n]);\n\nconst MARKDOWN_RENDERER_REF = 'technical-documentation:renderer/markdown';\n\nfunction relativeMarkdownPath(sourcePath: string, targetPath: string): string {\n  const relativePath = path.relative(path.dirname(sourcePath), targetPath);\n  return relativePath.startsWith('.') ? relativePath : `./${relativePath}`;\n}\n\nfunction renderLink(link: TechnicalDocumentationLinkV1, model: TechnicalDocumentationRenderModel, sourcePath: string, resolveApiReferenceTarget?: (target: TechnicalDocumentationApiReferenceTargetV1) => string): string {\n  if (link.kind === TechnicalDocumentationLinkKind.UNIT) {\n    const targetPath = model.unitPathByRef.get(link.targetUnitRef as string);\n    if (targetPath === undefined) throw new Error(`technical-documentation link target is not in the authorized render model: ${link.targetUnitRef}`);\n    return `- [${link.label}](${relativeMarkdownPath(sourcePath, `markdown/${targetPath}.md`)})`;\n  }\n  if (link.kind === TechnicalDocumentationLinkKind.EXTERNAL) return `- [${link.label}](${link.externalUrl})`;\n  if (link.kind === TechnicalDocumentationLinkKind.API_REFERENCE) {\n    if (resolveApiReferenceTarget === undefined) throw new Error(`technical-documentation API-reference link was not resolved before Markdown rendering: ${link.linkRef}`);\n    return `- [${link.label}](${resolveApiReferenceTarget(link.apiReferenceTarget as TechnicalDocumentationApiReferenceTargetV1)})`;\n  }\n  return `- ${link.label}`;\n}\n\nfunction renderUnit(\n  unit: TechnicalDocumentationUnitV1,\n  model: TechnicalDocumentationRenderModel,\n  assetPathByRef: ReadonlyMap<string, string>,\n  resolveApiReferenceTarget?: (target: TechnicalDocumentationApiReferenceTargetV1) => string,\n): string {\n  const unitPath = model.unitPathByRef.get(unit.unitRef);\n  if (unitPath === undefined) throw new Error(`technical-documentation render model has no path for ${unit.unitRef}`);\n  const sourcePath = `markdown/${unitPath}.md`;\n  const publishedPaths = new Set(model.unitPathByRef.values());\n  const sections = unit.sections.map((section, index) => {\n    const body = pruneUnpublishedSiteLinks(section.bodyMarkdown, publishedPaths, ENGINE_UNIT_ROUTES);\n    return isImplicitLeadSection(section, index) ? body : `## ${section.heading}\\n\\n${body}`;\n  }).join('\\n\\n');\n  const links = unit.links.length === 0 ? '' : `\\n\\n## Related\\n\\n${unit.links.map((link) => renderLink(link, model, sourcePath, resolveApiReferenceTarget)).join('\\n')}`;\n  const figures = unit.assetRequests.flatMap((request) => {\n    const assetPath = assetPathByRef.get(request.assetRef);\n    return assetPath === undefined ? [] : [`![${request.altText}](${relativeMarkdownPath(sourcePath, assetPath)})`];\n  });\n  const assetSection = figures.length === 0 ? '' : `\\n\\n## Product view\\n\\n${figures.join('\\n\\n')}`;\n  return `# ${unit.title}\\n\\n${unit.summary}\\n\\n${sections}${assetSection}${links}\\n`;\n}\n\nexport function renderTechnicalDocumentationMarkdown(input: {\n  readonly model: TechnicalDocumentationRenderModel;\n  readonly resolvedAssetBundle: TechnicalDocumentationResolvedAssetBundleManifestV1;\n  readonly assetBytesByPath: ReadonlyMap<string, Uint8Array>;\n  readonly resolveApiReferenceTarget?: (target: TechnicalDocumentationApiReferenceTargetV1) => string;\n}): TechnicalDocumentationRendererResult {\n  const assetPathByRef = new Map(input.resolvedAssetBundle.resolvedAssetSet.assets.flatMap((asset) =>\n    RENDERABLE_ASSET_STATUSES.has(asset.status) ? [[asset.assetRef, asset.normalizedRelativePath as string]] : []));\n  const sourceUnitRefsByAssetRef = new Map<string, string[]>();\n  for (const unit of input.model.units) {\n    for (const request of unit.assetRequests) {\n      const owners = sourceUnitRefsByAssetRef.get(request.assetRef) ?? [];\n      owners.push(unit.unitRef);\n      sourceUnitRefsByAssetRef.set(request.assetRef, owners);\n    }\n  }\n  const assetFiles = input.resolvedAssetBundle.resolvedAssetSet.assets.flatMap((asset) => {\n    if (!RENDERABLE_ASSET_STATUSES.has(asset.status)) return [];\n    const path = asset.normalizedRelativePath as string;\n    const bytes = input.assetBytesByPath.get(path);\n    if (bytes === undefined) throw new Error(`technical-documentation Markdown asset bytes are absent: ${path}`);\n    const sourceUnitRefs = [...(sourceUnitRefsByAssetRef.get(asset.assetRef) ?? [])].sort();\n    if (sourceUnitRefs.length === 0) throw new Error(`technical-documentation resolved asset has no authorized unit owner: ${asset.assetRef}`);\n    return [{\n      outputRef: `technical-documentation:output/markdown-asset/${technicalDocumentationAssetFileStem(asset.assetRef)}`,\n      rendererRef: MARKDOWN_RENDERER_REF,\n      outputKind: TechnicalDocumentationOutputKind.ASSET,\n      sourceUnitRefs,\n      normalizedRelativePath: path,\n      mediaType: asset.mediaType,\n      bytes,\n    }];\n  });\n  return {\n    execution: createTechnicalDocumentationRendererExecution({\n      rendererKind: TechnicalDocumentationRendererKind.MARKDOWN,\n      rendererRef: MARKDOWN_RENDERER_REF,\n      rendererVersion: 1,\n      configurationRef: 'technical-documentation:renderer-configuration/markdown-v1',\n    }),\n    files: [...input.model.units.map((unit) => {\n      const path = input.model.unitPathByRef.get(unit.unitRef) as string;\n      return {\n        // Keep the complete route identity: final path segments are not a\n        // globally unique page identity once consumer documentation has domains.\n        outputRef: `technical-documentation:output/markdown/${path.split('/').join(':')}`,\n        rendererRef: MARKDOWN_RENDERER_REF,\n        outputKind: TechnicalDocumentationOutputKind.MARKDOWN_DOCUMENT,\n        sourceUnitRefs: [unit.unitRef],\n        normalizedRelativePath: `markdown/${path}.md`,\n        mediaType: 'text/markdown',\n        bytes: Buffer.from(renderUnit(unit, input.model, assetPathByRef, input.resolveApiReferenceTarget), 'utf8'),\n      };\n    }), ...assetFiles],\n  };\n}\nimport { posix as path } from 'node:path';\n"]}