@ankhorage/paradox 0.1.26 → 0.2.0

package/dist/cli/index.d.ts

@@ -1,6 +1,7 @@
 /***
- * Generates deterministic documentation for a package through the Paradox CLI.
+ * Exposes the Paradox command provider through the canonical Ankhorage CLI surface.
  *
- * @readme
+ * @title CLI
+ * @usage
  */
 export { default } from '../docsSurface.js';

package/dist/cli/index.js

@@ -1,6 +1,7 @@
 /***
- * Generates deterministic documentation for a package through the Paradox CLI.
+ * Exposes the Paradox command provider through the canonical Ankhorage CLI surface.
  *
- * @readme
+ * @title CLI
+ * @usage
  */
 export { default } from '../docsSurface.js';

package/dist/cli/standalone.js

@@ -23,10 +23,21 @@ async function main() {
     const packageRoot = await resolvePackageRoot(config, configDir);
     const { outputDir, outputRoot } = resolveOutputRoot(config, packageRoot);
     const analysis = await analyze(config, { packageRoot, configFilePath });
+    assertNoDocumentationErrors(analysis.findings);
     const model = buildModel(analysis);
     const result = render(model, { outputDir });
     await write(result, config, { packageRoot, outputRoot });
 }
+/***
+ * Refuses to write generated artifacts when canonical documentation policy contains errors.
+ */
+function assertNoDocumentationErrors(findings) {
+    const errors = findings.filter((finding) => finding.severity === 'error');
+    if (errors.length === 0)
+        return;
+    const details = errors.map((finding) => `- [${finding.ruleId}] ${finding.message}`).join('\n');
+    throw new Error(`Paradox documentation policy is invalid:\n${details}`);
+}
 main().catch((error) => {
     console.error(error);
     process.exit(1);

package/dist/config/defineParadoxConfig.d.ts

@@ -1,4 +1,4 @@
-import type { ParadoxConfig } from './types.js';
+import type { ParadoxConfig } from '../types/config.js';
 /***
  * Defines a Paradox configuration object without changing its shape.
  *

package/dist/doc-tags/registry.d.ts

@@ -1,39 +1,35 @@
-export declare const PARADOX_DOC_TAGS: readonly [{
-    readonly name: "readme";
-    readonly syntax: "@readme";
-    readonly description: "Includes a documentation block or exported symbol in README output.";
-    readonly appliesTo: readonly ["block", "symbol"];
-    readonly repeatable: false;
-    readonly handler: "markReadme";
-}, {
-    readonly name: "config";
-    readonly syntax: "@config";
-    readonly description: "Marks a configuration type, interface, or source block. Pair with @readme to include the schema or actual config source in README Configuration output.";
-    readonly appliesTo: readonly ["block", "interface", "type"];
-    readonly repeatable: false;
-    readonly handler: "markConfig";
-}, {
-    readonly name: "example";
-    readonly syntax: "@example";
-    readonly description: "Adds a titled fenced code example to the generated documentation for a symbol.";
-    readonly appliesTo: readonly ["symbol"];
-    readonly repeatable: true;
-    readonly handler: "parseExample";
-}, {
-    readonly name: "usage";
-    readonly syntax: "@usage";
-    readonly description: "Promotes a real source example into the generated README Usage section.";
-    readonly appliesTo: readonly ["block", "symbol"];
-    readonly repeatable: false;
-    readonly handler: "markUsage";
-}];
-export type ParadoxDocTagName = (typeof PARADOX_DOC_TAGS)[number]['name'];
-export type ParadoxDocTagHandlerId = (typeof PARADOX_DOC_TAGS)[number]['handler'];
+import { type DocumentationTagName, type DocumentationTagTarget, type DocumentationTagValueKind } from '@ankhorage/policy/documentation';
+declare const HANDLERS: {
+    readonly readme: "markReadme";
+    readonly usage: "markUsage";
+    readonly config: "markConfig";
+    readonly title: "setTitle";
+    readonly see: "addSee";
+    readonly security: "addSecurity";
+};
+interface ParadoxDocTag {
+    name: DocumentationTagName;
+    syntax: string;
+    description: string;
+    appliesTo: readonly DocumentationTagTarget[];
+    repeatable: boolean;
+    valueKind: DocumentationTagValueKind;
+    handler: (typeof HANDLERS)[DocumentationTagName];
+}
+/***
+ * Supported Paradox documentation tags projected from the canonical Ankhorage documentation policy.
+ *
+ * @readme
+ */
+export declare const PARADOX_DOC_TAGS: readonly ParadoxDocTag[];
+export type ParadoxDocTagName = DocumentationTagName;
+export type ParadoxDocTagHandlerId = (typeof HANDLERS)[DocumentationTagName];
 /***
  * Looks up documentation tag metadata by tag name.
  */
-export declare function getParadoxDocTag(name: string): (typeof PARADOX_DOC_TAGS)[number] | null;
+export declare function getParadoxDocTag(name: string): ParadoxDocTag | null;
 /***
  * Checks whether a string is a supported Paradox documentation tag name.
  */
 export declare function isParadoxDocTagName(name: string): name is ParadoxDocTagName;
+export {};

package/dist/doc-tags/registry.js

@@ -1,46 +1,23 @@
+import { DOCUMENTATION_POLICY, } from '@ankhorage/policy/documentation';
+const HANDLERS = {
+    readme: 'markReadme',
+    usage: 'markUsage',
+    config: 'markConfig',
+    title: 'setTitle',
+    see: 'addSee',
+    security: 'addSecurity',
+};
 /***
- * Supported Paradox documentation tags.
- *
- * Paradox supports doc tags inside triple-star documentation comments.
+ * Supported Paradox documentation tags projected from the canonical Ankhorage documentation policy.
  *
  * @readme
  */
-const DOC_TAG_PREFIX = '\u0040';
-const USAGE_DOC_TAG = `${DOC_TAG_PREFIX}usage`;
-export const PARADOX_DOC_TAGS = [
-    {
-        name: 'readme',
-        syntax: '@readme',
-        description: 'Includes a documentation block or exported symbol in README output.',
-        appliesTo: ['block', 'symbol'],
-        repeatable: false,
-        handler: 'markReadme',
-    },
-    {
-        name: 'config',
-        syntax: '@config',
-        description: 'Marks a configuration type, interface, or source block. Pair with @readme to include the schema or actual config source in README Configuration output.',
-        appliesTo: ['block', 'interface', 'type'],
-        repeatable: false,
-        handler: 'markConfig',
-    },
-    {
-        name: 'example',
-        syntax: '@example',
-        description: 'Adds a titled fenced code example to the generated documentation for a symbol.',
-        appliesTo: ['symbol'],
-        repeatable: true,
-        handler: 'parseExample',
-    },
-    {
-        name: 'usage',
-        syntax: USAGE_DOC_TAG,
-        description: 'Promotes a real source example into the generated README Usage section.',
-        appliesTo: ['block', 'symbol'],
-        repeatable: false,
-        handler: 'markUsage',
-    },
-];
+export const PARADOX_DOC_TAGS = DOCUMENTATION_POLICY.tags.map((tag) => ({
+    ...tag,
+    syntax: `@${tag.name}`,
+    description: describeTag(tag.name),
+    handler: HANDLERS[tag.name],
+}));
 /***
  * Looks up documentation tag metadata by tag name.
  */
@@ -53,3 +30,22 @@ export function getParadoxDocTag(name) {
 export function isParadoxDocTagName(name) {
     return getParadoxDocTag(name) !== null;
 }
+/***
+ * Describes the rendering meaning of one policy-owned documentation tag.
+ */
+function describeTag(name) {
+    switch (name) {
+        case 'readme':
+            return 'Promotes the documented item into generated README output.';
+        case 'usage':
+            return 'Marks real source as package usage documentation.';
+        case 'config':
+            return 'Marks the canonical package configuration schema root.';
+        case 'title':
+            return 'Provides an explicit presentation title for a documented item.';
+        case 'see':
+            return 'Adds a validated external documentation reference.';
+        case 'security':
+            return 'Links security-sensitive behavior to an exact colocated executable test.';
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { defineParadoxConfig } from './config/defineParadoxConfig.js';
-export type { ParadoxConfig } from './config/types.js';
 export type { ParadoxDocTagHandlerId, ParadoxDocTagName } from './doc-tags/registry.js';
 export { getParadoxDocTag, isParadoxDocTagName, PARADOX_DOC_TAGS } from './doc-tags/registry.js';
 export { packageMetadata as paradoxPackageMetadata } from './packageMetadata.js';
+export type { ParadoxConfig } from './types/config.js';

package/dist/model/buildModel.d.ts

@@ -1,9 +1,4 @@
 import type { DocumentationModel, ExportKind } from './types.js';
-interface ExampleInput {
-    title: string | null;
-    language: string | null;
-    code: string;
-}
 interface ExportMemberInput {
     name: string;
     kind: 'property' | 'method';
@@ -39,9 +34,11 @@ interface BuildModelInput {
     }[];
     exports: {
         name: string;
+        title: string | null;
         description: string | null;
         isReadme: boolean;
-        examples: ExampleInput[];
+        see: string[];
+        security: string[];
         kind: ExportKind;
         modulePath: string;
         sourceLocation: {
@@ -71,7 +68,8 @@ interface BuildModelInput {
         name: string;
         description: string | null;
         isReadme: boolean;
-        examples: ExampleInput[];
+        see: string[];
+        security: string[];
         modulePath: string;
         sourceLocation: {
             filePath: string;
@@ -90,6 +88,8 @@ interface BuildModelInput {
     sourceFunctions: {
         name: string;
         description: string | null;
+        see: string[];
+        security: string[];
         sourceLocation: {
             filePath: string;
             line: number;
@@ -106,32 +106,39 @@ interface BuildModelInput {
     }[];
     usage: {
         packageName: string;
-        commands: {
-            name: string;
-            command: string;
-        }[];
-    } | null;
-    readmeUsageDescription: string | null;
-    readmeUsage: {
+        command: string;
+    };
+    usageEntries: {
+        area: 'cli' | 'examples';
         title: string | null;
         description: string | null;
         language: string;
         code: string;
         sourcePath: string;
+        isReadme: boolean;
+        see: string[];
+        security: string[];
+    }[];
+    exampleCount: number;
+    findings: {
+        ruleId: string;
+        severity: 'warning' | 'error';
+        message: string;
+        sourcePath: string | null;
+        line: number | null;
     }[];
-    readmeCli: {
-        description: string | null;
-        sourcePath: string;
-    } | null;
     readmeConfig: {
-        description: string | null;
         language: string;
         code: string;
         sourcePath: string;
     } | null;
     config: {
         exportName: string;
+        title: string | null;
+        description: string | null;
         isReadme: boolean;
+        see: string[];
+        security: string[];
         members: ConfigMemberInput[];
     } | null;
     entrypoints: string[];

package/dist/model/buildModel.js

@@ -4,87 +4,45 @@
 export function buildModel(analysis) {
     const exportNames = new Set(analysis.exports.map((item) => item.name));
     const exportsByName = new Map(analysis.exports.map((item) => [item.name, mapExport(item, exportNames)]));
-    const exports = sortByName([...exportsByName.values()]);
     return {
         packageName: analysis.packageName,
         packageId: analysis.packageId,
         description: analysis.description,
         collaborators: analysis.collaborators,
         donation: analysis.donation === null ? null : { account: analysis.donation.account },
-        badges: analysis.badges.map((badge) => ({
-            id: badge.id,
-            label: badge.label,
-            value: badge.value,
-            color: badge.color,
-        })),
-        usage: analysis.usage !== null
-            ? {
-                packageName: analysis.usage.packageName,
-                commands: sortByName(analysis.usage.commands.map((command) => ({
-                    name: command.name,
-                    command: command.command,
-                }))),
-            }
-            : null,
-        readmeUsageDescription: analysis.readmeUsageDescription,
-        readmeUsage: analysis.readmeUsage
-            .map((usageEntry) => ({
-            title: usageEntry.title,
-            description: usageEntry.description,
-            language: usageEntry.language,
-            code: usageEntry.code,
-            sourcePath: usageEntry.sourcePath,
-        }))
+        badges: analysis.badges.map((badge) => ({ ...badge })),
+        usage: { ...analysis.usage },
+        usageEntries: analysis.usageEntries
+            .map((entry) => ({ ...entry, see: [...entry.see], security: [...entry.security] }))
             .sort((left, right) => left.sourcePath.localeCompare(right.sourcePath)),
-        readmeCli: analysis.readmeCli !== null
-            ? {
-                description: analysis.readmeCli.description,
-                sourcePath: analysis.readmeCli.sourcePath,
-            }
-            : null,
-        readmeConfig: analysis.readmeConfig !== null
-            ? {
-                description: analysis.readmeConfig.description,
-                language: analysis.readmeConfig.language,
-                code: analysis.readmeConfig.code,
-                sourcePath: analysis.readmeConfig.sourcePath,
-            }
-            : null,
-        config: analysis.config !== null
-            ? {
-                exportName: analysis.config.exportName,
-                isReadme: analysis.config.isReadme,
+        exampleCount: analysis.exampleCount,
+        findings: analysis.findings.map((finding) => ({ ...finding })),
+        readmeConfig: analysis.readmeConfig === null ? null : { ...analysis.readmeConfig },
+        config: analysis.config === null
+            ? null
+            : {
+                ...analysis.config,
+                see: [...analysis.config.see],
+                security: [...analysis.config.security],
                 members: analysis.config.members,
-            }
-            : null,
+            },
         entrypoints: [...analysis.entrypoints].sort((a, b) => a.localeCompare(b)),
         modules: [...analysis.modules]
             .map((module) => ({
-            path: module.path,
-            isEntrypoint: module.isEntrypoint,
+            ...module,
             dependencies: [...module.dependencies].sort((a, b) => a.localeCompare(b)),
             exports: [...module.exports].sort((a, b) => a.localeCompare(b)),
         }))
             .sort((left, right) => left.path.localeCompare(right.path)),
-        exports,
+        exports: sortByName([...exportsByName.values()]),
         components: sortByName(analysis.components.map((component) => mapComponent(component, exportsByName.get(component.name)))),
         sourceFunctions: analysis.sourceFunctions.map((sourceFunction) => ({
-            name: sourceFunction.name,
-            description: sourceFunction.description,
-            sourceLocation: {
-                filePath: sourceFunction.sourceLocation.filePath,
-                line: sourceFunction.sourceLocation.line,
-                column: sourceFunction.sourceLocation.column,
-            },
+            ...sourceFunction,
+            see: [...sourceFunction.see],
+            security: [...sourceFunction.security],
+            sourceLocation: { ...sourceFunction.sourceLocation },
         })),
-        sequenceScenarios: sortByName(analysis.sequenceScenarios.map((scenario) => ({
-            kind: scenario.kind,
-            name: scenario.name,
-            sourcePath: scenario.sourcePath,
-            symbolName: scenario.symbolName,
-            description: scenario.description,
-            isReadme: scenario.isReadme,
-        }))),
+        sequenceScenarios: sortByName(analysis.sequenceScenarios.map((scenario) => ({ ...scenario }))),
         graphs: {
             imports: [...analysis.graphs.imports],
             calls: [...analysis.graphs.calls],
@@ -99,39 +57,24 @@ export function buildModel(analysis) {
 function mapExport(item, exportNames) {
     return {
         name: item.name,
+        title: item.title,
         description: item.description,
         isReadme: item.isReadme,
-        examples: item.examples.map((example) => ({ ...example })),
+        see: [...item.see],
+        security: [...item.security],
         kind: item.kind,
         modulePath: item.modulePath,
-        sourceLocation: {
-            filePath: item.sourceLocation.filePath,
-            line: item.sourceLocation.line,
-            column: item.sourceLocation.column,
-        },
+        sourceLocation: { ...item.sourceLocation },
         exportPaths: [...item.exportPaths].sort((a, b) => a.localeCompare(b)),
         relatedSymbols: item.relatedSymbols
             .filter((symbol) => exportNames.has(symbol))
             .sort((a, b) => a.localeCompare(b)),
         signatures: item.signatures.map((signature) => ({
-            label: signature.label,
-            parameters: sortByName(signature.parameters.map((parameter) => ({
-                name: parameter.name,
-                type: parameter.type,
-                required: parameter.required,
-                description: parameter.description,
-            }))),
-            returnType: signature.returnType,
-            returnDescription: signature.returnDescription,
+            ...signature,
+            parameters: sortByName(signature.parameters.map((parameter) => ({ ...parameter }))),
         })),
         members: sortByName(item.members.map((member) => ({
-            name: member.name,
-            kind: member.kind,
-            type: member.type,
-            required: member.required,
-            description: member.description,
-            defaultValue: member.defaultValue,
-            inheritedFrom: member.inheritedFrom,
+            ...member,
             children: member.children,
         }))),
         structuredRows: item.structuredRows.map((row) => ({ values: { ...row.values } })),
@@ -145,25 +88,16 @@ function mapComponent(component, exportModel) {
         name: component.name,
         description: component.description,
         isReadme: component.isReadme,
-        examples: component.examples.map((example) => ({ ...example })),
+        see: [...component.see],
+        security: [...component.security],
         modulePath: component.modulePath,
-        sourceLocation: {
-            filePath: component.sourceLocation.filePath,
-            line: component.sourceLocation.line,
-            column: component.sourceLocation.column,
-        },
+        sourceLocation: { ...component.sourceLocation },
         exportPaths: exportModel?.exportPaths ?? [...component.exportPaths].sort((a, b) => a.localeCompare(b)),
-        props: sortByName(component.props.map((prop) => ({
-            name: prop.name,
-            type: prop.type,
-            required: prop.required,
-            defaultValue: prop.defaultValue,
-            description: prop.description,
-        }))),
+        props: sortByName(component.props.map((prop) => ({ ...prop }))),
     };
 }
 /***
- * Returns a copy of items sorted by their `name` property.
+ * Returns a copy of items sorted by their name property.
  */
 function sortByName(items) {
     return [...items].sort((a, b) => a.name.localeCompare(b.name));

package/dist/model/types.d.ts

@@ -1,3 +1,4 @@
+import type { PolicySeverity } from '@ankhorage/policy/status';
 /***
  * Serializable model consumed by renderers and writers.
  */
@@ -8,10 +9,10 @@ export interface DocumentationModel {
     collaborators: true | null;
     donation: DonationModel | null;
     badges: GeneratedBadge[];
-    usage: UsageModel | null;
-    readmeUsageDescription: string | null;
-    readmeUsage: ReadmeUsageModel[];
-    readmeCli: ReadmeCliModel | null;
+    usage: UsageModel;
+    usageEntries: UsageEntryModel[];
+    exampleCount: number;
+    findings: DocumentationFindingModel[];
     readmeConfig: ReadmeConfigModel | null;
     config: ConfigModel | null;
     entrypoints: string[];
@@ -33,39 +34,47 @@ export interface GeneratedBadge {
 }
 interface UsageModel {
     packageName: string;
-    commands: UsageCommandModel[];
-}
-interface UsageCommandModel {
-    name: string;
     command: string;
 }
-interface ReadmeUsageModel {
+interface UsageEntryModel {
+    area: 'cli' | 'examples';
     title: string | null;
     description: string | null;
     language: string;
     code: string;
     sourcePath: string;
+    isReadme: boolean;
+    see: string[];
+    security: string[];
 }
-interface ReadmeCliModel {
-    description: string | null;
-    sourcePath: string;
+interface DocumentationFindingModel {
+    ruleId: string;
+    severity: PolicySeverity;
+    message: string;
+    sourcePath: string | null;
+    line: number | null;
 }
 interface ReadmeConfigModel {
-    description: string | null;
     language: string;
     code: string;
     sourcePath: string;
 }
 interface ConfigModel {
     exportName: string;
+    title: string | null;
+    description: string | null;
     isReadme: boolean;
+    see: string[];
+    security: string[];
     members: ConfigMemberModel[];
 }
 export interface ExportModel {
     name: string;
+    title: string | null;
     description: string | null;
     isReadme: boolean;
-    examples: ExampleModel[];
+    see: string[];
+    security: string[];
     kind: ExportKind;
     modulePath: string;
     sourceLocation: SourceLocationModel;
@@ -80,7 +89,8 @@ export interface ComponentModel {
     name: string;
     description: string | null;
     isReadme: boolean;
-    examples: ExampleModel[];
+    see: string[];
+    security: string[];
     modulePath: string;
     sourceLocation: SourceLocationModel;
     exportPaths: string[];
@@ -89,6 +99,8 @@ export interface ComponentModel {
 interface SourceFunctionModel {
     name: string;
     description: string | null;
+    see: string[];
+    security: string[];
     sourceLocation: SourceLocationModel;
 }
 export interface SequenceScenarioModel {
@@ -105,11 +117,6 @@ export interface ModuleModel {
     dependencies: string[];
     exports: string[];
 }
-interface ExampleModel {
-    title: string | null;
-    language: string | null;
-    code: string;
-}
 interface SourceLocationModel {
     filePath: string;
     line: number;

package/dist/paths/policy.d.ts

@@ -1,4 +1,4 @@
-import type { ParadoxConfig } from '../config/types.js';
+import type { ParadoxConfig } from '../types/config.js';
 /***
  * Searches upward from a start directory until it finds a supported Paradox config file.
  */

package/dist/render/renderers/diagrams.js

@@ -1,3 +1,4 @@
+import { toFileStem } from '../toFileStem.js';
 const MAX_SEQUENCE_CALL_EDGES = 12;
 const MAX_SEQUENCE_PARTICIPANTS = 8;
 const MAX_BIN_SEQUENCE_PARTICIPANTS = 12;
@@ -193,13 +194,6 @@ function renderFallbackEdge(modules, prefix) {
 function uniqueSorted(values) {
     return [...new Set(values)].sort((left, right) => left.localeCompare(right));
 }
-function toFileStem(value) {
-    return value
-        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
-        .replace(/[^A-Za-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '')
-        .toLowerCase();
-}
 function toMermaidId(value) {
     return value.replace(/[^A-Za-z0-9_]/g, '_');
 }