@ankhorage/paradox 0.0.6 → 0.0.7

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.0.7
+
+### Patch Changes
+
+- 5246138: Generate deterministic README quality badges from local repository metadata.
+
+  Paradox now computes README badge metadata from local package, TypeScript, linting, formatting, workflow, test, coverage, and documentation signals, then renders stable local SVG badge assets under `paradox/badges/` and includes them in generated README output without relying on external badge services.
+
 ## 0.0.6
 
 ### Patch Changes

package/README.md

@@ -1,5 +1,7 @@
 # @ankhorage/paradox
 
+![license: MIT](./paradox/badges/license.svg) ![npm: v0.0.6](./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)
+
 Deterministic documentation generator for TypeScript packages.
 
 ## Usage
@@ -39,6 +41,7 @@ graph TD
   package__ankhorage_paradox --> entrypoint_src_index_ts
   module_src_analyze_analyze_ts["src/analyze/analyze.ts"]
   package__ankhorage_paradox -.-> module_src_analyze_analyze_ts
+  module_src_analyze_analyze_ts --> module_src_analyze_badges_ts
   module_src_analyze_analyze_ts --> module_src_analyze_components_ts
   module_src_analyze_analyze_ts --> module_src_analyze_exports_ts
   module_src_analyze_analyze_ts --> module_src_analyze_modules_ts
@@ -46,6 +49,10 @@ graph TD
   module_src_analyze_analyze_ts --> module_src_analyze_types_ts
   module_src_analyze_analyze_ts --> module_src_analyze_usage_ts
   module_src_analyze_analyze_ts --> module_src_config_types_ts
+  module_src_analyze_badges_ts["src/analyze/badges.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_badges_ts
+  module_src_analyze_badges_ts --> module_src_analyze_types_ts
+  module_src_analyze_badges_ts --> module_src_analyze_usage_ts
   module_src_analyze_components_ts["src/analyze/components.ts"]
   package__ankhorage_paradox -.-> module_src_analyze_components_ts
   module_src_analyze_components_ts --> module_src_analyze_types_ts
@@ -113,10 +120,15 @@ graph TD
   module_src_render_render_ts["src/render/render.ts"]
   package__ankhorage_paradox -.-> module_src_render_render_ts
   module_src_render_render_ts --> module_src_model_types_ts
+  module_src_render_render_ts --> module_src_render_renderers_badges_ts
   module_src_render_render_ts --> module_src_render_renderers_diagrams_ts
   module_src_render_render_ts --> module_src_render_renderers_html_ts
   module_src_render_render_ts --> module_src_render_renderers_markdown_ts
   module_src_render_render_ts --> module_src_render_types_ts
+  module_src_render_renderers_badges_ts["src/render/renderers/badges.ts"]
+  package__ankhorage_paradox -.-> module_src_render_renderers_badges_ts
+  module_src_render_renderers_badges_ts --> module_src_model_types_ts
+  module_src_render_renderers_badges_ts --> module_src_render_types_ts
   module_src_render_renderers_diagrams_ts["src/render/renderers/diagrams.ts"]
   package__ankhorage_paradox -.-> module_src_render_renderers_diagrams_ts
   module_src_render_renderers_diagrams_ts --> module_src_model_types_ts

package/dist/analyze/analyze.js

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { analyzeBadges } from './badges.js';
 import { analyzeComponents } from './components.js';
 import { analyzeExports } from './exports.js';
 import { analyzeModules } from './modules.js';
@@ -12,6 +13,7 @@ export async function analyze(config, runtime) {
     const root = runtime.packageRoot;
     const pkg = await readPackageJson(root);
     const usage = createUsageFromPackageJson(pkg);
+    const badges = await analyzeBadges(root, pkg);
     const project = createProject(root);
     const entrypoints = config.package?.entrypoints ?? ['src/index.ts'];
     const { config: configMetadata, exports } = analyzeExports(project, {
@@ -31,6 +33,7 @@ export async function analyze(config, runtime) {
         components,
         entrypoints: entrypoints.map((entrypoint) => entrypoint.replaceAll('\\', '/')).sort(),
         modules,
+        badges,
         usage,
         config: configMetadata,
     };

package/dist/analyze/badges.d.ts

@@ -0,0 +1,6 @@
+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[]>;

package/dist/analyze/badges.js

@@ -0,0 +1,256 @@
+import { access, readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const ESLINT_CONFIG_FILES = [
+    'eslint.config.js',
+    'eslint.config.mjs',
+    'eslint.config.cjs',
+    'eslint.config.ts',
+    '.eslintrc',
+    '.eslintrc.js',
+    '.eslintrc.cjs',
+    '.eslintrc.json',
+    '.eslintrc.yaml',
+    '.eslintrc.yml',
+];
+const PRETTIER_CONFIG_FILES = [
+    '.prettierrc',
+    '.prettierrc.js',
+    '.prettierrc.cjs',
+    '.prettierrc.json',
+    '.prettierrc.yaml',
+    '.prettierrc.yml',
+    'prettier.config.js',
+    'prettier.config.cjs',
+    'prettier.config.mjs',
+    'prettier.config.ts',
+];
+const BADGE_ORDER = [
+    'license',
+    'npm',
+    'runtime',
+    'typescript',
+    'eslint',
+    'prettier',
+    'build',
+    'tests',
+    'coverage',
+    'docs',
+];
+/***
+ * Derives deterministic repository metadata badges from local repository files.
+ */
+export async function analyzeBadges(root, pkg) {
+    const workflowFiles = await readWorkflowFiles(root);
+    const badges = [];
+    if ((await hasAnyFile(root, ESLINT_CONFIG_FILES)) ||
+        pkg.eslintConfig !== undefined ||
+        scriptContains(pkg, 'lint', 'eslint')) {
+        badges.push({
+            id: 'eslint',
+            label: 'eslint',
+            value: workflowRunsScript(workflowFiles, 'lint') ? 'checked' : 'configured',
+            color: workflowRunsScript(workflowFiles, 'lint') ? '0a7f3f' : '2563eb',
+        });
+    }
+    if ((await hasAnyFile(root, PRETTIER_CONFIG_FILES)) ||
+        pkg.prettier !== undefined ||
+        scriptContains(pkg, 'format', 'prettier') ||
+        scriptContains(pkg, 'format:check', 'prettier')) {
+        const prettierChecked = workflowRunsScript(workflowFiles, 'format') ||
+            workflowRunsScript(workflowFiles, 'format:check');
+        badges.push({
+            id: 'prettier',
+            label: 'prettier',
+            value: prettierChecked ? 'checked' : 'configured',
+            color: prettierChecked ? '0a7f3f' : '2563eb',
+        });
+    }
+    if (hasScript(pkg, 'build')) {
+        const buildChecked = workflowRunsScript(workflowFiles, 'build');
+        badges.push({
+            id: 'build',
+            label: 'build',
+            value: buildChecked ? 'checked' : 'configured',
+            color: buildChecked ? '0a7f3f' : '6f42c1',
+        });
+    }
+    if (hasScript(pkg, 'test')) {
+        const testsChecked = workflowRunsScript(workflowFiles, 'test');
+        badges.push({
+            id: 'tests',
+            label: 'tests',
+            value: testsChecked ? 'checked' : 'configured',
+            color: testsChecked ? '0a7f3f' : '6f42c1',
+        });
+    }
+    if (await hasTypeScriptStrictMode(root)) {
+        badges.push({
+            id: 'typescript',
+            label: 'typescript',
+            value: 'strict',
+            color: '2563eb',
+        });
+    }
+    if (supportsBun(pkg, workflowFiles)) {
+        badges.push({
+            id: 'runtime',
+            label: 'runtime',
+            value: 'bun',
+            color: 'f59e0b',
+        });
+    }
+    const coverage = await readCoveragePercent(root);
+    if (coverage !== null) {
+        badges.push({
+            id: 'coverage',
+            label: 'coverage',
+            value: `${formatPercent(coverage)}%`,
+            color: getCoverageColor(coverage),
+        });
+    }
+    if (typeof pkg.license === 'string' && pkg.license.length > 0) {
+        badges.push({
+            id: 'license',
+            label: 'license',
+            value: pkg.license,
+            color: '2563eb',
+        });
+    }
+    if (typeof pkg.version === 'string' && pkg.version.length > 0) {
+        badges.push({
+            id: 'npm',
+            label: 'npm',
+            value: `v${pkg.version}`,
+            color: 'cb3837',
+        });
+    }
+    badges.push({
+        id: 'docs',
+        label: 'docs',
+        value: 'paradox',
+        color: '0f766e',
+    });
+    return sortBadges(badges);
+}
+async function hasAnyFile(root, paths) {
+    for (const relativePath of paths) {
+        if (await fileExists(join(root, relativePath))) {
+            return true;
+        }
+    }
+    return false;
+}
+async function hasTypeScriptStrictMode(root) {
+    const tsconfig = await readJsonFile(join(root, 'tsconfig.json'));
+    return tsconfig?.compilerOptions?.strict === true;
+}
+async function readCoveragePercent(root) {
+    const coverage = await readJsonFile(join(root, 'coverage', 'coverage-summary.json'));
+    const value = coverage?.total?.lines?.pct;
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function formatPercent(value) {
+    return Number.isInteger(value) ? `${value}` : value.toFixed(1);
+}
+function getCoverageColor(value) {
+    if (value >= 90)
+        return '0a7f3f';
+    if (value >= 75)
+        return '65a30d';
+    if (value >= 50)
+        return 'ca8a04';
+    return 'dc2626';
+}
+function hasScript(pkg, name) {
+    return typeof pkg.scripts?.[name] === 'string' && pkg.scripts[name].length > 0;
+}
+function scriptContains(pkg, name, command) {
+    return pkg.scripts?.[name]?.includes(command) ?? false;
+}
+function supportsBun(pkg, workflowFiles) {
+    if (pkg.packageManager?.startsWith('bun@') ?? false) {
+        return true;
+    }
+    if (Object.values(pkg.scripts ?? {}).some((script) => script.includes('bun') || script.includes('bunx'))) {
+        return true;
+    }
+    return workflowFiles.some((workflow) => workflow.includes('oven-sh/setup-bun') ||
+        workflow.includes('bun install') ||
+        /\bbun(?:x)?\b/.test(workflow));
+}
+function workflowRunsScript(workflowFiles, scriptName) {
+    const escaped = escapeRegExp(scriptName);
+    const patterns = [
+        new RegExp(`\\bbun\\s+run\\s+${escaped}(?=\\s|$)`, 'i'),
+        new RegExp(`\\bnpm\\s+run\\s+${escaped}(?=\\s|$)`, 'i'),
+        new RegExp(`\\bpnpm\\s+${escaped}(?=\\s|$)`, 'i'),
+        new RegExp(`\\byarn\\s+${escaped}(?=\\s|$)`, 'i'),
+    ];
+    return workflowFiles.some((workflow) => patterns.some((pattern) => pattern.test(workflow)));
+}
+function escapeRegExp(value) {
+    return value.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+async function readWorkflowFiles(root) {
+    const workflowsPath = join(root, '.github', 'workflows');
+    const entries = await readDirectory(workflowsPath);
+    const contents = await Promise.all(entries
+        .filter((entry) => entry.endsWith('.yml') || entry.endsWith('.yaml'))
+        .sort((a, b) => a.localeCompare(b))
+        .map((entry) => readFile(join(workflowsPath, entry), 'utf-8')));
+    return contents;
+}
+async function readDirectory(path) {
+    try {
+        return await readdir(path);
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return [];
+        }
+        throw new Error(`Unable to read workflow directory: ${path}`, { cause: error });
+    }
+}
+function isNotFoundError(error) {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
+}
+async function readJsonFile(path) {
+    let content;
+    try {
+        content = await readFile(path, 'utf-8');
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return null;
+        }
+        throw new Error(`Unable to read JSON metadata file: ${path}`, { cause: error });
+    }
+    try {
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`Unable to parse JSON metadata file: ${path}`, { cause: error });
+    }
+}
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return false;
+        }
+        throw error;
+    }
+}
+function sortBadges(badges) {
+    return [...badges].sort((left, right) => {
+        const order = getBadgeOrder(left.id) - getBadgeOrder(right.id);
+        return order !== 0 ? order : left.id.localeCompare(right.id);
+    });
+}
+function getBadgeOrder(id) {
+    const index = BADGE_ORDER.indexOf(id);
+    return index === -1 ? BADGE_ORDER.length : index;
+}

package/dist/analyze/types.d.ts

@@ -62,6 +62,12 @@ export interface AnalysisUsageCommand {
     name: string;
     command: string;
 }
+export interface AnalysisBadge {
+    id: string;
+    label: string;
+    value: string;
+    color: string;
+}
 export interface AnalysisModule {
     path: string;
     isEntrypoint: boolean;
@@ -79,6 +85,7 @@ export interface AnalysisResult {
     components: AnalysisComponent[];
     entrypoints: string[];
     modules: AnalysisModule[];
+    badges: AnalysisBadge[];
     usage: AnalysisUsage | null;
     config: {
         exportName: string;

package/dist/analyze/usage.d.ts

@@ -2,6 +2,12 @@ import type { AnalysisUsage } from './types.js';
 export interface PackageJsonModel {
     name: string;
     description?: string;
+    version?: string;
+    license?: string;
+    packageManager?: string;
     bin?: string | Record<string, string>;
+    scripts?: Record<string, string>;
+    eslintConfig?: unknown;
+    prettier?: unknown;
 }
 export declare function createUsageFromPackageJson(pkg: PackageJsonModel): AnalysisUsage | null;

package/dist/model/buildModel.d.ts

@@ -3,6 +3,12 @@ interface BuildModelInput {
     packageName: string;
     packageId: string;
     description: string | null;
+    badges: {
+        id: string;
+        label: string;
+        value: string;
+        color: string;
+    }[];
     exports: {
         name: string;
         description: string | null;

package/dist/model/buildModel.js

@@ -9,6 +9,12 @@ export function buildModel(analysis) {
         packageName: analysis.packageName,
         packageId: analysis.packageId,
         description: analysis.description,
+        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,

package/dist/model/types.d.ts

@@ -5,6 +5,7 @@ export interface DocumentationModel {
     packageName: string;
     packageId: string;
     description: string | null;
+    badges: GeneratedBadge[];
     usage: UsageModel | null;
     config: ConfigModel | null;
     entrypoints: string[];
@@ -12,6 +13,12 @@ export interface DocumentationModel {
     exports: ExportModel[];
     components: ComponentModel[];
 }
+export interface GeneratedBadge {
+    id: string;
+    label: string;
+    value: string;
+    color: string;
+}
 export interface UsageModel {
     packageName: string;
     commands: UsageCommandModel[];

package/dist/render/render.js

@@ -1,3 +1,4 @@
+import { renderBadgeArtifacts } from './renderers/badges.js';
 import { renderDiagramArtifacts } from './renderers/diagrams.js';
 import { renderHtml } from './renderers/html.js';
 import { renderMarkdown } from './renderers/markdown.js';
@@ -5,6 +6,7 @@ import { renderMarkdown } from './renderers/markdown.js';
  * Renders the documentation model into README and artifact files.
  */
 export function render(model, options = {}) {
+    const badges = renderBadgeArtifacts(model);
     const diagrams = renderDiagramArtifacts(model);
     const outputDir = options.outputDir ?? 'paradox';
     const result = {
@@ -14,11 +16,13 @@ export function render(model, options = {}) {
         exportsJson: `${JSON.stringify(model.exports, null, 2)}\n`,
         paradoxJson: `${JSON.stringify(model, null, 2)}\n`,
         indexHtml: '',
+        badges,
         diagrams,
     };
     const context = {
         model,
         outputDir,
+        badges,
         diagrams,
         result,
     };

package/dist/render/renderers/badges.d.ts

@@ -0,0 +1,6 @@
+import type { DocumentationModel } from '../../model/types.js';
+import type { BadgeArtifact } from '../types.js';
+/***
+ * Renders deterministic local SVG badges for repository metadata.
+ */
+export declare function renderBadgeArtifacts(model: DocumentationModel): BadgeArtifact[];

package/dist/render/renderers/badges.js

@@ -0,0 +1,35 @@
+/***
+ * Renders deterministic local SVG badges for repository metadata.
+ */
+export function renderBadgeArtifacts(model) {
+    return model.badges.map((badge) => ({
+        path: `badges/${badge.id}.svg`,
+        content: renderBadgeSvg(badge),
+    }));
+}
+function renderBadgeSvg(badge) {
+    const labelWidth = getTextWidth(badge.label);
+    const valueWidth = getTextWidth(badge.value);
+    const totalWidth = labelWidth + valueWidth;
+    return [
+        `<svg xmlns="http://www.w3.org/2000/svg" width="${totalWidth}" height="20" role="img" aria-label="${escapeXml(`${badge.label}: ${badge.value}`)}">`,
+        `<title>${escapeXml(`${badge.label}: ${badge.value}`)}</title>`,
+        `<rect width="${labelWidth}" height="20" fill="#374151"/>`,
+        `<rect x="${labelWidth}" width="${valueWidth}" height="20" fill="#${badge.color}"/>`,
+        `<text x="${labelWidth / 2}" y="14" fill="#ffffff" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11" text-anchor="middle">${escapeXml(badge.label)}</text>`,
+        `<text x="${labelWidth + valueWidth / 2}" y="14" fill="#ffffff" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11" text-anchor="middle">${escapeXml(badge.value)}</text>`,
+        '</svg>',
+        '',
+    ].join('\n');
+}
+function getTextWidth(value) {
+    return Math.max(38, value.length * 7 + 10);
+}
+function escapeXml(value) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&apos;');
+}

package/dist/render/renderers/markdown.d.ts

@@ -2,4 +2,4 @@ import type { RenderContext } from '../types.js';
 /***
  * Renders markdown artifacts from the documentation model.
  */
-export declare function renderMarkdown({ diagrams, model, outputDir, }: RenderContext): Pick<RenderContext['result'], 'components' | 'exportsMarkdown' | 'readme'>;
+export declare function renderMarkdown({ badges, diagrams, model, outputDir, }: RenderContext): Pick<RenderContext['result'], 'components' | 'exportsMarkdown' | 'readme'>;

package/dist/render/renderers/markdown.js

@@ -1,15 +1,20 @@
 /***
  * Renders markdown artifacts from the documentation model.
  */
-export function renderMarkdown({ diagrams, model, outputDir, }) {
+export function renderMarkdown({ badges, diagrams, model, outputDir, }) {
     return {
-        readme: renderReadme(model, outputDir, diagrams),
+        readme: renderReadme(model, outputDir, badges, diagrams),
         exportsMarkdown: renderExports(model),
         components: renderComponents(model),
     };
 }
-function renderReadme(model, outputDir, diagrams) {
+function renderReadme(model, outputDir, badges, diagrams) {
     const lines = [`# ${model.packageName}`, ''];
+    if (badges.length > 0) {
+        lines.push(badges
+            .map((badge) => `![${badgeLabel(model, badge.path)}](./${outputDir}/${badge.path})`)
+            .join(' '), '');
+    }
     if (model.description) {
         lines.push(model.description, '');
     }
@@ -139,3 +144,12 @@ function renderComponents(model) {
 function escapeTableCell(value) {
     return value.replaceAll('|', '\\|');
 }
+function badgeLabel(model, badgePath) {
+    const fileName = badgePath.split('/').pop();
+    if (!fileName) {
+        return badgePath;
+    }
+    const id = fileName.replace(/\.svg$/, '');
+    const badge = model.badges.find((entry) => entry.id === id);
+    return badge ? `${badge.label}: ${badge.value}` : badgePath;
+}

package/dist/render/types.d.ts

@@ -7,6 +7,10 @@ export interface DiagramArtifact {
     title: string;
     content: string;
 }
+export interface BadgeArtifact {
+    path: string;
+    content: string;
+}
 export interface RenderResult {
     readme: string;
     exportsMarkdown: string;
@@ -15,10 +19,12 @@ export interface RenderResult {
     paradoxJson: string;
     indexHtml: string;
     diagrams: DiagramArtifact[];
+    badges: BadgeArtifact[];
 }
 export interface RenderContext {
     model: DocumentationModel;
     outputDir: string;
     diagrams: DiagramArtifact[];
+    badges: BadgeArtifact[];
     result: RenderResult;
 }

package/dist/write/write.js

@@ -13,6 +13,11 @@ export async function write(result, config, runtime) {
     await writeFile(join(outputRoot, 'exports.json'), result.exportsJson);
     await writeFile(join(outputRoot, 'paradox.json'), result.paradoxJson);
     await writeFile(join(outputRoot, 'index.html'), result.indexHtml);
+    for (const badge of result.badges) {
+        const badgePath = join(outputRoot, badge.path);
+        await mkdir(dirname(badgePath), { recursive: true });
+        await writeFile(badgePath, badge.content);
+    }
     for (const diagram of result.diagrams) {
         const diagramPath = join(outputRoot, diagram.path);
         await mkdir(dirname(diagramPath), { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/paradox",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Deterministic documentation generator for TypeScript packages.",
   "license": "MIT",
   "publishConfig": {