@ankhorage/paradox 0.1.26 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.2.0
+
+### Minor Changes
+
+- 9fe93b9: Adopt the canonical Ankhorage documentation policy: fixed usage and config locations, source-backed
+  examples, explicit titles, validated external and security references, policy-derived status
+  badges, and hard failures for invalid documentation contracts.
+
+## 0.1.27
+
+### Patch Changes
+
+- ef42af1: Reuse the canonical Utility ASCII slugifier for generated HTML anchor ids.
+
 ## 0.1.26
 
 ### Patch Changes

package/README.md

@@ -3,66 +3,44 @@
 
 # @ankhorage/paradox
 
-![license: MIT](./paradox/badges/license.svg) ![npm: v0.1.25](./paradox/badges/npm.svg) ![runtime: bun](./paradox/badges/runtime.svg) ![typescript: strict](./paradox/badges/typescript.svg) ![eslint: checked](./paradox/badges/eslint.svg) ![prettier: checked](./paradox/badges/prettier.svg) ![build: checked](./paradox/badges/build.svg) ![tests: checked](./paradox/badges/tests.svg) ![docs: paradox](./paradox/badges/docs.svg)
+![license: MIT](./paradox/badges/license.svg) ![npm: v0.1.27](./paradox/badges/npm.svg) ![runtime: bun](./paradox/badges/runtime.svg) ![typescript: strict](./paradox/badges/typescript.svg) ![eslint: checked](./paradox/badges/eslint.svg) ![prettier: checked](./paradox/badges/prettier.svg) ![build: checked](./paradox/badges/build.svg) ![tests: checked](./paradox/badges/tests.svg) ![paradox: canonical](./paradox/badges/docs.svg)
 
 Deterministic documentation generator for TypeScript packages.
 
-## CLI
+## Usage
 
-Generates deterministic documentation for a package through the Paradox CLI.
+### CLI
 
-```bash
-bunx @ankhorage/paradox
-```
+Ankhorage packages expose their command-line interface through `ankh`. Use `ankh --help` to discover available package commands, or run a package command with `--help` for package-specific usage.
 
-<details>
-<summary>paradox</summary>
-
-Runs the Paradox CLI.
-
-The command discovers the nearest Paradox config, resolves the package and output roots,
-analyzes the package, builds the documentation model, renders all documentation artifacts,
-and writes them to the configured output directory.
-
-Diagram: [paradox sequence](./paradox/diagrams/sequences/paradox.mmd)
-
-```mermaid
-sequenceDiagram
-  participant participant_analyze as analyze
-  participant participant_buildModel as buildModel
-  participant participant_dirname as dirname
-  participant participant_findParadoxConfigFile as findParadoxConfigFile
-  participant participant_loadParadoxConfig as loadParadoxConfig
-  participant participant_main as main
-  participant participant_render as render
-  participant participant_resolveOutputRoot as resolveOutputRoot
-  participant participant_resolvePackageRoot as resolvePackageRoot
-  participant participant_write as write
-  participant_main->>participant_findParadoxConfigFile: findParadoxConfigFile()
-  participant_findParadoxConfigFile-->>participant_main: return
-  participant_main->>participant_dirname: dirname()
-  participant_dirname-->>participant_main: return
-  participant_main->>participant_loadParadoxConfig: loadParadoxConfig()
-  participant_loadParadoxConfig-->>participant_main: return
-  participant_main->>participant_resolvePackageRoot: resolvePackageRoot()
-  participant_resolvePackageRoot-->>participant_main: return
-  participant_main->>participant_resolveOutputRoot: resolveOutputRoot()
-  participant_resolveOutputRoot-->>participant_main: return
-  participant_main->>participant_analyze: analyze()
-  participant_analyze-->>participant_main: return
-  participant_main->>participant_buildModel: buildModel()
-  participant_buildModel-->>participant_main: return
-  participant_main->>participant_render: render()
-  participant_render-->>participant_main: return
-  participant_main->>participant_write: write()
-  participant_write-->>participant_main: return
+```zsh
+# Install the Ankhorage CLI
+bun add --global @ankhorage/ankh
+
+# Show usage information for paradox
+ankh paradox --help
 ```
 
-</details>
+### Basic Usage
+
+Paradox generates documentation from the canonical package structure. Usage documentation lives
+only below `examples/**` or `src/cli/**`. A repository may contain multiple `@usage`
+examples, but exactly one example below `examples/**` is promoted into README with `@readme`.
+
+README-promoted usage provides an explicit `@title` and non-empty prose. Code always comes from
+real source declarations rather than duplicated code blocks inside Paradox comments.
+
+```ts
+export const basicConfig = defineParadoxConfig({
+  mode: 'safe',
+});
+```
 
 ## Configuration
 
-Canonical Paradox configuration for this package.
+Configures Paradox documentation generation for a package.
+
+### Example
 
 ```ts
 import { defineParadoxConfig } from './src/config/defineParadoxConfig.js';
@@ -89,14 +67,14 @@ export default defineParadoxConfig({
 <details>
 <summary>Configuration options</summary>
 
-| Field         | Type                                                                                                                | Required | Default | Description |
-| ------------- | ------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ----------- |
-| mode          | `'safe' \| 'write' \| undefined`                                                                                    | no       | —       |             |
-| collaborators | `true \| undefined`                                                                                                 | no       | —       |             |
-| donation      | `{ account: string; } \| undefined`                                                                                 | no       | —       |             |
-| docs          | `{ title?: string; description?: string; usage?: { description?: string; entrypoints?: string[]; }; } \| undefined` | no       | —       |             |
-| package       | `{ root?: string; entrypoints?: string[]; } \| undefined`                                                           | no       | —       |             |
-| output        | `{ dir?: string; } \| undefined`                                                                                    | no       | —       |             |
+| Field         | Type                                                      | Required | Default | Description |
+| ------------- | --------------------------------------------------------- | -------- | ------- | ----------- |
+| mode          | `'safe' \| 'write' \| undefined`                          | no       | —       |             |
+| collaborators | `true \| undefined`                                       | no       | —       |             |
+| donation      | `{ account: string; } \| undefined`                       | no       | —       |             |
+| docs          | `{ title?: string; description?: string; } \| undefined`  | no       | —       |             |
+| package       | `{ root?: string; entrypoints?: string[]; } \| undefined` | no       | —       |             |
+| output        | `{ dir?: string; } \| undefined`                          | no       | —       |             |
 
 </details>
 
@@ -130,13 +108,27 @@ Related symbols: `ParadoxConfig`
 
 </details>
 
+### Documentation
+
+<details>
+<summary>PARADOX_DOC_TAGS</summary>
+
+Supported Paradox documentation tags projected from the canonical Ankhorage documentation policy.
+
+Module: `src/doc-tags/registry.ts`
+Source: `src/doc-tags/registry.ts:32:14`
+
+</details>
+
+### Types
+
 <details>
-<summary>ParadoxConfig</summary>
+<summary>Configuration</summary>
 
-Configuration for running Paradox.
+Configures Paradox documentation generation for a package.
 
-Module: `src/config/types.ts`
-Source: `src/config/types.ts:7:1`
+Module: `src/types/config.ts`
+Source: `src/types/config.ts:9:1`
 
 </details>
 

package/dist/analyze/analyze.d.ts

@@ -1,7 +1,7 @@
-import type { ParadoxConfig } from '../config/types.js';
+import type { ParadoxConfig } from '../types/config.js';
 import type { AnalysisResult } from './types.js';
 /***
- * Analyzes a package and returns the complete documentation input model.
+ * Analyzes a package and returns documentation plus canonical policy findings.
  */
 export declare function analyze(config: ParadoxConfig, runtime: {
     packageRoot: string;

package/dist/analyze/analyze.js

@@ -1,15 +1,17 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { resolvePolicyStatus } from '@ankhorage/policy/status';
 import { validateCollaborators } from '../config/utils/validateCollaborators.js';
 import { validateDonationAccount } from '../config/utils/validateDonationAccount.js';
 import { analyzeBadges } from './badges.js';
 import { analyzeComponents } from './components.js';
+import { collectDocumentationCommentsAsync } from './documentation/collectDocumentationCommentsAsync.js';
+import { validateDocumentationPolicyAsync } from './documentation/validateDocumentationPolicyAsync.js';
 import { analyzeExports } from './exports.js';
 import { analyzeModules } from './modules.js';
 import { createProject } from './project.js';
-import { analyzeReadmeCli } from './readmeCli.js';
 import { analyzeReadmeConfig } from './readmeConfig.js';
-import { analyzeReadmeUsage } from './readmeUsage.js';
+import { analyzeReadmeUsage, countExampleDirectoriesAsync } from './readmeUsage.js';
 import { createTypeScriptProgram } from './semantic/createTypeScriptProgram.js';
 import { collectTypeMembers, resolveTypeReference } from './semantic/exports.js';
 import { collectCallGraph, collectComponentCompositionGraph, collectImportGraph, } from './semantic/graphs.js';
@@ -17,7 +19,7 @@ import { analyzeSequenceScenarios } from './sequenceScenarios.js';
 import { analyzeSourceFunctions } from './sourceFunctions.js';
 import { createUsageFromPackageJson } from './usage.js';
 /***
- * Analyzes a package and returns the complete documentation input model.
+ * Analyzes a package and returns documentation plus canonical policy findings.
  */
 export async function analyze(config, runtime) {
     const root = runtime.packageRoot;
@@ -27,38 +29,22 @@ export async function analyze(config, runtime) {
         ? null
         : { account: validateDonationAccount(config.donation.account) };
     const usage = createUsageFromPackageJson(pkg);
-    const badges = await analyzeBadges(root, pkg);
     const project = createProject(root);
     const entrypoints = config.package?.entrypoints ?? ['src/index.ts'];
-    const readmeUsageDescription = config.docs?.usage?.description ?? null;
-    const usageEntryPoints = config.docs?.usage?.entrypoints ?? [];
-    const readmeUsage = await analyzeReadmeUsage({ root, entrypoints: usageEntryPoints });
-    const readmeCli = await analyzeReadmeCli(root);
-    const readmeConfig = await analyzeReadmeConfig({
-        root,
-        configFilePath: runtime.configFilePath ?? null,
-    });
     const program = createTypeScriptProgram({ root, entrypoints, project });
     const { config: configMetadata, exports } = analyzeExports(project, { root, entrypoints });
     const components = analyzeComponents(exports, { program });
-    const modules = analyzeModules(project, {
-        root,
-        entrypoints,
-        excludePaths: usageEntryPoints,
-    });
+    const modules = analyzeModules(project, { root, entrypoints });
     const sourceFunctions = analyzeSourceFunctions(project, root);
     const sequenceScenarios = analyzeSequenceScenarios({ project, root, pkg, exports });
-    const configExport = configMetadata
-        ? (exports.find((entry) => entry.name === configMetadata.exportName) ?? null)
-        : null;
-    const configMembers = configExport && (configExport.kind === 'type' || configExport.kind === 'unknown')
-        ? collectTypeMembers(program, resolveTypeReference(program, configExport.node) ?? {
-            type: configExport.node.getType(),
-            name: configExport.name,
-            sourcePath: configExport.modulePath,
-            symbol: configExport.node.getSymbol() ?? null,
-        })
-        : [];
+    const usageEntries = await analyzeReadmeUsage({ root });
+    const exampleCount = await countExampleDirectoriesAsync(root);
+    const comments = await collectDocumentationCommentsAsync(root);
+    const readmeConfig = await analyzeReadmeConfig({
+        root,
+        configFilePath: runtime.configFilePath ?? null,
+    });
+    const configMembers = collectConfigMembers(program, exports, configMetadata);
     const graphs = {
         imports: collectImportGraph(program),
         calls: collectCallGraph(program),
@@ -69,6 +55,14 @@ export async function analyze(config, runtime) {
         }))),
         componentComposition: collectComponentCompositionGraph(program),
     };
+    const findings = await validateDocumentationPolicyAsync({
+        root,
+        project,
+        comments,
+        exports,
+    });
+    const documentationStatus = resolvePolicyStatus(findings);
+    const badges = await analyzeBadges(root, pkg, documentationStatus.status);
     return {
         packageName: config.docs?.title ?? pkg.name,
         packageId: pkg.name,
@@ -83,20 +77,42 @@ export async function analyze(config, runtime) {
         badges,
         sequenceScenarios,
         usage,
-        readmeUsageDescription,
-        readmeUsage,
-        readmeCli,
+        usageEntries,
+        exampleCount,
+        findings,
         readmeConfig,
-        config: configMetadata
-            ? {
+        config: configMetadata === null
+            ? null
+            : {
                 exportName: configMetadata.exportName,
+                title: configMetadata.title,
+                description: configMetadata.description,
                 isReadme: configMetadata.isReadme,
+                see: configMetadata.see,
+                security: configMetadata.security,
                 members: mapTypeMembers(configMembers),
-            }
-            : null,
+            },
         graphs,
     };
 }
+/***
+ * Resolves member metadata for the public configuration root when one exists.
+ */
+function collectConfigMembers(program, exports, configMetadata) {
+    if (configMetadata === null)
+        return [];
+    const configExport = exports.find((entry) => entry.name === configMetadata.exportName);
+    if (configExport === undefined ||
+        (configExport.kind !== 'type' && configExport.kind !== 'unknown')) {
+        return [];
+    }
+    return collectTypeMembers(program, resolveTypeReference(program, configExport.node) ?? {
+        type: configExport.node.getType(),
+        name: configExport.name,
+        sourcePath: configExport.modulePath,
+        symbol: configExport.node.getSymbol() ?? null,
+    });
+}
 /***
  * Converts semantic type members into serializable analysis output.
  */

package/dist/analyze/badges.d.ts

@@ -1,6 +1,7 @@
+import type { PolicyStatus } from '@ankhorage/policy/status';
 import type { AnalysisBadge } from './types.js';
 import type { PackageJsonModel } from './usage.js';
 /***
  * Derives deterministic repository metadata badges from local repository files.
  */
-export declare function analyzeBadges(root: string, pkg: PackageJsonModel): Promise<AnalysisBadge[]>;
+export declare function analyzeBadges(root: string, pkg: PackageJsonModel, documentationStatus: PolicyStatus): Promise<AnalysisBadge[]>;

package/dist/analyze/badges.js

@@ -39,7 +39,7 @@ const BADGE_ORDER = [
 /***
  * Derives deterministic repository metadata badges from local repository files.
  */
-export async function analyzeBadges(root, pkg) {
+export async function analyzeBadges(root, pkg, documentationStatus) {
     const workflowFiles = await readWorkflowFiles(root);
     const badges = [];
     if ((await hasAnyFile(root, ESLINT_CONFIG_FILES)) ||
@@ -126,9 +126,9 @@ export async function analyzeBadges(root, pkg) {
     }
     badges.push({
         id: 'docs',
-        label: 'docs',
-        value: 'paradox',
-        color: '0f766e',
+        label: 'paradox',
+        value: documentationStatus,
+        color: getDocumentationStatusColor(documentationStatus),
     });
     return sortBadges(badges);
 }
@@ -305,3 +305,13 @@ function getBadgeOrder(id) {
     const index = BADGE_ORDER.indexOf(id);
     return index === -1 ? BADGE_ORDER.length : index;
 }
+/***
+ * Maps the shared traffic-light status to a deterministic badge color.
+ */
+function getDocumentationStatusColor(status) {
+    if (status === 'invalid')
+        return 'dc2626';
+    if (status === 'warnings')
+        return 'ca8a04';
+    return '0a7f3f';
+}

package/dist/analyze/components.js

@@ -7,11 +7,11 @@ import { isReactComponent } from './utils/isReactComponent.js';
  */
 export function analyzeComponents(exports, options = {}) {
     const components = [];
-    for (const e of exports) {
-        if (!isReactComponent(e.node))
+    for (const entry of exports) {
+        if (!isReactComponent(entry.node))
             continue;
         const propsFromAnalyzer = options.program
-            ? collectPropsForExport(options.program, { name: e.name, node: e.node })
+            ? collectPropsForExport(options.program, { name: entry.name, node: entry.node })
             : undefined;
         const analyzerProps = propsFromAnalyzer?.members.map((member) => ({
             name: member.name,
@@ -20,17 +20,18 @@ export function analyzeComponents(exports, options = {}) {
             ...(member.defaultValue !== undefined ? { defaultValue: member.defaultValue } : {}),
             description: member.description ?? null,
         })) ?? [];
-        const propsType = getComponentPropsType(e.node);
+        const propsType = getComponentPropsType(entry.node);
         const legacyProps = propsType != null ? getPropsFromType(propsType, options.program?.root) : [];
         const props = analyzerProps.length > 0 ? analyzerProps : legacyProps;
         components.push({
-            name: e.name,
-            description: e.description,
-            isReadme: e.isReadme,
-            examples: e.examples,
-            modulePath: e.modulePath,
-            sourceLocation: e.sourceLocation,
-            exportPaths: e.exportPaths,
+            name: entry.name,
+            description: entry.description,
+            isReadme: entry.isReadme,
+            see: entry.see,
+            security: entry.security,
+            modulePath: entry.modulePath,
+            sourceLocation: entry.sourceLocation,
+            exportPaths: entry.exportPaths,
             props,
         });
     }

package/dist/analyze/documentation/collectDocumentationCommentsAsync.d.ts

@@ -0,0 +1,11 @@
+import type { ParsedParadoxComment } from '../utils/parseParadoxComment.js';
+export interface CollectedDocumentationComment {
+    readonly sourcePath: string;
+    readonly line: number;
+    readonly raw: string;
+    readonly parsed: ParsedParadoxComment;
+}
+/***
+ * Collects real Paradox comments from canonical source roots and source-like repository root files.
+ */
+export declare function collectDocumentationCommentsAsync(root: string): Promise<CollectedDocumentationComment[]>;

package/dist/analyze/documentation/collectDocumentationCommentsAsync.js

@@ -0,0 +1,72 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { extname, join, relative } from 'node:path';
+import { parseParadoxComment } from '../utils/parseParadoxComment.js';
+const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.json5']);
+const SCANNED_ROOTS = ['src', 'examples'];
+const COMMENT_PATTERN = /\/\*\*\*[\s\S]*?\*\//g;
+/***
+ * Collects real Paradox comments from canonical source roots and source-like repository root files.
+ */
+export async function collectDocumentationCommentsAsync(root) {
+    const nestedFiles = (await Promise.all(SCANNED_ROOTS.map((name) => collectSourceFilesAsync(join(root, name))))).flat();
+    const rootFiles = await collectRootSourceFilesAsync(root);
+    const files = [...new Set([...nestedFiles, ...rootFiles])].sort((a, b) => a.localeCompare(b));
+    const comments = await Promise.all(files.map((filePath) => collectFileCommentsAsync(root, filePath)));
+    return comments.flat();
+}
+/***
+ * Collects supported source files recursively while treating missing canonical roots as empty.
+ */
+async function collectSourceFilesAsync(root) {
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isMissingPathError(error))
+            return [];
+        throw error;
+    }
+    const nested = await Promise.all(entries.map(async (entry) => {
+        const path = join(root, entry.name);
+        if (entry.isDirectory())
+            return collectSourceFilesAsync(path);
+        return entry.isFile() && SOURCE_EXTENSIONS.has(extname(entry.name)) ? [path] : [];
+    }));
+    return nested.flat();
+}
+/***
+ * Collects source-like files directly at repository root.
+ */
+async function collectRootSourceFilesAsync(root) {
+    const entries = await readdir(root, { withFileTypes: true });
+    return entries.flatMap((entry) => entry.isFile() && SOURCE_EXTENSIONS.has(extname(entry.name)) ? [join(root, entry.name)] : []);
+}
+/***
+ * Collects Paradox comments from one source file with stable line locations.
+ */
+async function collectFileCommentsAsync(root, filePath) {
+    const source = await readFile(filePath, 'utf-8');
+    const sourcePath = toPosixPath(relative(root, filePath));
+    return [...source.matchAll(COMMENT_PATTERN)].map((match) => {
+        const [raw] = match;
+        return {
+            sourcePath,
+            line: source.slice(0, match.index).split('\n').length,
+            raw,
+            parsed: parseParadoxComment(raw),
+        };
+    });
+}
+/***
+ * Checks whether a filesystem error reports a missing path.
+ */
+function isMissingPathError(error) {
+    return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+}
+/***
+ * Normalizes filesystem separators for stable documentation paths.
+ */
+function toPosixPath(path) {
+    return path.replaceAll('\\', '/');
+}

package/dist/analyze/documentation/findings.d.ts

@@ -0,0 +1,5 @@
+import type { AnalysisDocumentationFinding } from '../types.js';
+/***
+ * Creates a finding from one canonical documentation policy rule.
+ */
+export declare function createDocumentationFinding(ruleId: string, message: string, sourcePath?: string | null, line?: number | null): AnalysisDocumentationFinding;

package/dist/analyze/documentation/findings.js

@@ -0,0 +1,17 @@
+import { DOCUMENTATION_POLICY } from '@ankhorage/policy/documentation';
+/***
+ * Creates a finding from one canonical documentation policy rule.
+ */
+export function createDocumentationFinding(ruleId, message, sourcePath = null, line = null) {
+    const rule = DOCUMENTATION_POLICY.rules.find((candidate) => candidate.id === ruleId);
+    if (rule === undefined) {
+        throw new Error(`Unknown documentation policy rule: ${ruleId}`);
+    }
+    return {
+        ruleId,
+        severity: rule.severity,
+        message,
+        sourcePath,
+        line,
+    };
+}

package/dist/analyze/documentation/validateDocumentationPolicyAsync.d.ts

@@ -0,0 +1,13 @@
+import { type Project } from 'ts-morph';
+import type { AnalysisDocumentationFinding, AnalysisExport } from '../types.js';
+import type { CollectedDocumentationComment } from './collectDocumentationCommentsAsync.js';
+/***
+ * Evaluates package documentation evidence against the canonical Ankhorage documentation policy.
+ */
+export declare function validateDocumentationPolicyAsync(options: {
+    root: string;
+    project: Project;
+    comments: readonly CollectedDocumentationComment[];
+    exports: readonly AnalysisExport[];
+    validateSeeUrlAsync?: (url: string) => Promise<unknown>;
+}): Promise<AnalysisDocumentationFinding[]>;