@unrdf/diataxis-kit 26.4.2

package/src/hash.mjs

@@ -0,0 +1,37 @@
+/**
+ * @file Hashing utilities using stable JSON stringification
+ * @module hash
+ */
+
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { stableStringify } from './stable-json.mjs';
+
+/**
+ * Hash an object deterministically using SHA256
+ * @param {any} obj - Object to hash
+ * @returns {string} Hex-encoded SHA256 hash
+ */
+export function hashObject(obj) {
+  const json = stableStringify(obj, { indent: 0 });
+  return hashString(json);
+}
+
+/**
+ * Hash a string using SHA256
+ * @param {string} str - String to hash
+ * @returns {string} Hex-encoded SHA256 hash
+ */
+export function hashString(str) {
+  return createHash('sha256').update(str, 'utf8').digest('hex');
+}
+
+/**
+ * Hash a file's contents using SHA256
+ * @param {string} filePath - Path to file
+ * @returns {Promise<string>} Hex-encoded SHA256 hash
+ */
+export async function hashFile(filePath) {
+  const content = await readFile(filePath, 'utf8');
+  return hashString(content);
+}

package/src/inventory.mjs

@@ -0,0 +1,280 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, resolve, dirname } from 'node:path';
+import { existsSync } from 'node:fs';
+
+/**
+ * @typedef {Object} PackageEntry
+ * @property {string} name - Package name
+ * @property {string} dir - Absolute path to package directory
+ * @property {string} version - Package version
+ * @property {string} description - Package description
+ * @property {Record<string, string>} exports - Package exports map
+ * @property {Record<string, string> | string} bin - Binary executables
+ * @property {string[]} keywords - Package keywords
+ * @property {boolean} hasReadme - Whether README.md exists
+ * @property {boolean} hasDocs - Whether docs/ directory exists
+ * @property {boolean} hasExamples - Whether examples/ directory exists
+ * @property {boolean} hasTests - Whether test/ directory exists
+ * @property {Record<string, string>} scripts - Selected scripts (test, dev, build)
+ */
+
+/**
+ * Discovers all workspace packages and returns structured metadata
+ * @param {string} workspaceRoot - Path to monorepo root
+ * @param {Object} [options={}] - Discovery options
+ * @param {string[]} [options.skipDirs=['node_modules', '.git', 'dist', 'build']] - Directories to skip
+ * @param {boolean} [options.includeNested=true] - Whether to discover nested workspaces
+ * @returns {Promise<PackageEntry[]>} Array of package entries, sorted by name
+ */
+export async function discoverPackages(workspaceRoot, options = {}) {
+  const {
+    skipDirs = ['node_modules', '.git', 'dist', 'build'],
+    includeNested = true
+  } = options;
+
+  const rootPath = resolve(workspaceRoot);
+
+  // Detect workspace configuration
+  const workspacePatterns = await detectWorkspacePatterns(rootPath);
+
+  if (workspacePatterns.length === 0) {
+    console.warn('No workspace configuration found');
+  }
+
+  // Find all package.json files
+  const packagePaths = await findPackageJsonFiles(rootPath, skipDirs, includeNested);
+
+  // Process each package
+  const packages = [];
+  for (const pkgPath of packagePaths) {
+    try {
+      const entry = await processPackage(pkgPath);
+      if (entry) {
+        packages.push(entry);
+      }
+    } catch (error) {
+      console.warn(`Skipping package at ${pkgPath}: ${error.message}`);
+    }
+  }
+
+  // Sort by package name for stable ordering (deterministic)
+  packages.sort((a, b) => a.name.localeCompare(b.name));
+
+  return packages;
+}
+
+/**
+ * Validates a package entry structure
+ * @param {any} entry - Entry to validate
+ * @returns {{ valid: boolean, errors: string[] }} Validation result
+ */
+export function validatePackageEntry(entry) {
+  const errors = [];
+
+  if (!entry || typeof entry !== 'object') {
+    return { valid: false, errors: ['Entry must be an object'] };
+  }
+
+  // Check required string fields
+  const requiredStrings = ['name', 'dir', 'version', 'description'];
+  for (const field of requiredStrings) {
+    if (typeof entry[field] !== 'string') {
+      errors.push(`Field '${field}' must be a string`);
+    }
+  }
+
+  // Check exports (must be object)
+  if (typeof entry.exports !== 'object' || entry.exports === null) {
+    errors.push('Field \'exports\' must be an object');
+  }
+
+  // Check bin (can be object or string)
+  if (entry.bin !== null && typeof entry.bin !== 'object' && typeof entry.bin !== 'string') {
+    errors.push('Field \'bin\' must be an object, string, or null');
+  }
+
+  // Check keywords array
+  if (!Array.isArray(entry.keywords)) {
+    errors.push('Field \'keywords\' must be an array');
+  }
+
+  // Check boolean fields
+  const booleanFields = ['hasReadme', 'hasDocs', 'hasExamples', 'hasTests'];
+  for (const field of booleanFields) {
+    if (typeof entry[field] !== 'boolean') {
+      errors.push(`Field '${field}' must be a boolean`);
+    }
+  }
+
+  // Check scripts (must be object)
+  if (typeof entry.scripts !== 'object' || entry.scripts === null) {
+    errors.push('Field \'scripts\' must be an object');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * Detects workspace patterns from pnpm-workspace.yaml and package.json
+ * @param {string} rootPath - Root directory path
+ * @returns {Promise<string[]>} Array of workspace patterns
+ */
+async function detectWorkspacePatterns(rootPath) {
+  const patterns = [];
+
+  // Check pnpm-workspace.yaml
+  const pnpmWorkspacePath = join(rootPath, 'pnpm-workspace.yaml');
+  try {
+    if (existsSync(pnpmWorkspacePath)) {
+      const content = await readFile(pnpmWorkspacePath, 'utf-8');
+      // Simple YAML parsing for packages array
+      const lines = content.split('\n');
+      let inPackages = false;
+      for (const line of lines) {
+        if (line.trim().startsWith('packages:')) {
+          inPackages = true;
+          continue;
+        }
+        if (inPackages && line.trim().startsWith('-')) {
+          const pattern = line.trim().substring(1).trim().replace(/['"]/g, '');
+          patterns.push(pattern);
+        } else if (inPackages && line.trim() && !line.trim().startsWith('#')) {
+          // End of packages section (non-empty, non-comment line)
+          break;
+        }
+      }
+    }
+  } catch (error) {
+    // Gracefully skip if unable to read
+  }
+
+  // Check package.json workspaces
+  const pkgJsonPath = join(rootPath, 'package.json');
+  try {
+    if (existsSync(pkgJsonPath)) {
+      const content = await readFile(pkgJsonPath, 'utf-8');
+      const pkg = JSON.parse(content);
+      if (pkg.workspaces) {
+        if (Array.isArray(pkg.workspaces)) {
+          patterns.push(...pkg.workspaces);
+        } else if (pkg.workspaces.packages && Array.isArray(pkg.workspaces.packages)) {
+          patterns.push(...pkg.workspaces.packages);
+        }
+      }
+    }
+  } catch (error) {
+    // Gracefully skip if unable to read or parse
+  }
+
+  return patterns;
+}
+
+/**
+ * Recursively finds all package.json files
+ * @param {string} dir - Directory to search
+ * @param {string[]} skipDirs - Directories to skip
+ * @param {boolean} includeNested - Whether to include nested workspaces
+ * @returns {Promise<string[]>} Array of package.json file paths
+ */
+async function findPackageJsonFiles(dir, skipDirs, includeNested) {
+  const results = [];
+
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+
+      // Skip directories in skipDirs list
+      if (skipDirs.includes(entry.name)) {
+        continue;
+      }
+
+      if (entry.isDirectory()) {
+        // Recursively search subdirectories
+        const subResults = await findPackageJsonFiles(fullPath, skipDirs, includeNested);
+        results.push(...subResults);
+      } else if (entry.name === 'package.json') {
+        // Found a package.json file
+        results.push(fullPath);
+      }
+    }
+  } catch (error) {
+    // Gracefully ignore errors (e.g., permission denied)
+  }
+
+  return results;
+}
+
+/**
+ * Processes a single package.json file and extracts metadata
+ * @param {string} pkgJsonPath - Path to package.json
+ * @returns {Promise<PackageEntry | null>} Package entry or null if invalid
+ */
+async function processPackage(pkgJsonPath) {
+  try {
+    const content = await readFile(pkgJsonPath, 'utf-8');
+    const pkg = JSON.parse(content);
+
+    if (!pkg.name) {
+      // Skip packages without a name
+      return null;
+    }
+
+    const packageDir = dirname(pkgJsonPath);
+
+    // Extract selected scripts (test, dev, build only)
+    const scripts = {};
+    if (pkg.scripts) {
+      for (const scriptName of ['test', 'dev', 'build']) {
+        if (pkg.scripts[scriptName]) {
+          scripts[scriptName] = pkg.scripts[scriptName];
+        }
+      }
+    }
+
+    // Check for various files and directories
+    const hasReadme = existsSync(join(packageDir, 'README.md'));
+    const hasDocs = await checkDirectory(join(packageDir, 'docs'));
+    const hasExamples = await checkDirectory(join(packageDir, 'examples'));
+
+    // Check multiple common test directory names
+    const hasTests = await checkDirectory(join(packageDir, 'test')) ||
+                     await checkDirectory(join(packageDir, 'tests')) ||
+                     await checkDirectory(join(packageDir, '__tests__'));
+
+    return {
+      name: pkg.name,
+      dir: packageDir,
+      version: pkg.version || '0.0.0',
+      description: pkg.description || '',
+      exports: pkg.exports || {},
+      bin: pkg.bin || {},
+      keywords: pkg.keywords || [],
+      hasReadme,
+      hasDocs,
+      hasExamples,
+      hasTests,
+      scripts
+    };
+  } catch (error) {
+    throw new Error(`Failed to process package: ${error.message}`);
+  }
+}
+
+/**
+ * Checks if a directory exists
+ * @param {string} dirPath - Path to check
+ * @returns {Promise<boolean>} True if directory exists
+ */
+async function checkDirectory(dirPath) {
+  try {
+    const stats = await stat(dirPath);
+    return stats.isDirectory();
+  } catch (error) {
+    return false;
+  }
+}

package/src/reference-extractor.mjs

@@ -0,0 +1,324 @@
+/**
+ * @fileoverview Reference Extractor - Extract API surface from package metadata and README
+ * @module reference-extractor
+ *
+ * This module extracts API reference information from:
+ * - package.json exports field
+ * - package.json bin field
+ * - README API sections
+ *
+ * Used by classify.mjs to generate reference documentation structure.
+ */
+
+/**
+ * @typedef {Object} ReferenceItem
+ * @property {string} name - The API item name (export path, bin name, etc)
+ * @property {string} type - Item type: "export", "bin", "api", "unknown"
+ * @property {string} description - Description of the item
+ * @property {string|null} example - Optional usage example
+ */
+
+/**
+ * @typedef {Object} Reference
+ * @property {string} id - Always "reference"
+ * @property {string} title - Reference title (e.g., "[PackageName] API Reference")
+ * @property {ReferenceItem[]} items - List of reference items
+ * @property {number} confidenceScore - Confidence score 0-1
+ * @property {string[]} source - Sources that contributed data
+ */
+
+/**
+ * Extract API reference from package metadata and README
+ *
+ * @param {Object} packageEntry - Package.json data
+ * @param {Object} evidenceSnapshot - Contains README and other evidence
+ * @param {string} [evidenceSnapshot.readme] - README content
+ * @returns {Reference} Reference object with API items
+ *
+ * @example
+ * const ref = extractReference(pkg, { readme: '# API\n...' });
+ * // => { id: 'reference', title: 'pkg-name API Reference', items: [...], ... }
+ */
+export function extractReference(packageEntry, evidenceSnapshot) {
+  const items = [];
+  const sources = [];
+
+  // Extract from package.json exports field
+  const exportItems = extractFromExports(packageEntry);
+  if (exportItems.length > 0) {
+    items.push(...exportItems);
+    sources.push('exports');
+  }
+
+  // Extract from package.json bin field
+  const binItems = extractFromBin(packageEntry);
+  if (binItems.length > 0) {
+    items.push(...binItems);
+    sources.push('bin');
+  }
+
+  // Extract from README API sections
+  const readmeItems = extractFromReadme(evidenceSnapshot.readme || '');
+  if (readmeItems.length > 0) {
+    items.push(...readmeItems);
+    sources.push('readme');
+  }
+
+  // Fallback if nothing found
+  if (items.length === 0) {
+    items.push({
+      name: 'unknown',
+      type: 'unknown',
+      description: 'API reference not found in documentation',
+      example: null
+    });
+    sources.push('inferred');
+  }
+
+  // Sort items by name for deterministic output
+  items.sort((a, b) => a.name.localeCompare(b.name));
+
+  // Calculate confidence score
+  const confidenceScore = calculateConfidence(sources);
+
+  return {
+    id: 'reference',
+    title: `${packageEntry.name || 'Package'} API Reference`,
+    items,
+    confidenceScore,
+    source: sources
+  };
+}
+
+/**
+ * Extract reference items from package.json exports field
+ *
+ * @param {Object} packageEntry - Package.json data
+ * @returns {ReferenceItem[]} Array of reference items from exports
+ *
+ * @example
+ * extractFromExports({ exports: { '.': './index.js', './utils': './utils.js' } })
+ * // => [{ name: '.', type: 'export', description: './index.js', example: null }, ...]
+ */
+function extractFromExports(packageEntry) {
+  const items = [];
+
+  if (!packageEntry.exports) {
+    return items;
+  }
+
+  const exports = packageEntry.exports;
+
+  // Handle string exports (single entry point)
+  if (typeof exports === 'string') {
+    items.push({
+      name: '.',
+      type: 'export',
+      description: exports,
+      example: null
+    });
+    return items;
+  }
+
+  // Handle object exports
+  if (typeof exports === 'object' && exports !== null) {
+    for (const [exportPath, value] of Object.entries(exports)) {
+      // Handle conditional exports (import/require)
+      let description = '';
+      if (typeof value === 'string') {
+        description = value;
+      } else if (typeof value === 'object' && value !== null) {
+        // Use import condition first, fallback to require, then default
+        description = value.import || value.require || value.default || JSON.stringify(value);
+      }
+
+      items.push({
+        name: exportPath,
+        type: 'export',
+        description: String(description),
+        example: null
+      });
+    }
+  }
+
+  return items;
+}
+
+/**
+ * Extract reference items from package.json bin field
+ *
+ * @param {Object} packageEntry - Package.json data
+ * @returns {ReferenceItem[]} Array of reference items from bin
+ *
+ * @example
+ * extractFromBin({ bin: 'cli.js' })
+ * // => [{ name: 'package-name', type: 'bin', description: 'CLI entry point: cli.js', example: null }]
+ */
+function extractFromBin(packageEntry) {
+  const items = [];
+
+  if (!packageEntry.bin) {
+    return items;
+  }
+
+  const bin = packageEntry.bin;
+
+  // Handle string bin (single CLI entry point)
+  if (typeof bin === 'string') {
+    items.push({
+      name: packageEntry.name || 'cli',
+      type: 'bin',
+      description: `CLI entry point: ${bin}`,
+      example: null
+    });
+    return items;
+  }
+
+  // Handle object bin (multiple CLI commands)
+  if (typeof bin === 'object' && bin !== null) {
+    for (const [binName, binPath] of Object.entries(bin)) {
+      items.push({
+        name: binName,
+        type: 'bin',
+        description: `CLI entry point: ${binPath}`,
+        example: null
+      });
+    }
+  }
+
+  return items;
+}
+
+/**
+ * Extract reference items from README API sections
+ *
+ * Looks for headings like "API", "API Reference", "Exports", "CLI Options", "Options"
+ * and extracts the content following these headings.
+ *
+ * @param {string} readme - README content
+ * @returns {ReferenceItem[]} Array of reference items from README
+ *
+ * @example
+ * extractFromReadme('## API\n\n- foo: Does something\n- bar: Does another thing')
+ * // => [{ name: 'foo', type: 'api', description: 'Does something', ... }, ...]
+ */
+function extractFromReadme(readme) {
+  const items = [];
+
+  if (!readme || typeof readme !== 'string') {
+    return items;
+  }
+
+  // API section heading patterns (case-insensitive)
+  const apiHeadingPatterns = [
+    /^#{1,6}\s+API\s*$/im,
+    /^#{1,6}\s+API\s+Reference\s*$/im,
+    /^#{1,6}\s+Exports\s*$/im,
+    /^#{1,6}\s+CLI\s+Options\s*$/im,
+    /^#{1,6}\s+Options\s*$/im,
+    /^#{1,6}\s+Usage\s*$/im,
+    /^#{1,6}\s+Methods\s*$/im
+  ];
+
+  for (const pattern of apiHeadingPatterns) {
+    const match = readme.match(pattern);
+    if (!match) {
+      continue;
+    }
+
+    // Extract content after heading (next 500 chars or until next heading)
+    const startIndex = match.index + match[0].length;
+    const remainingContent = readme.slice(startIndex);
+
+    // Find next heading or take 500 chars
+    const nextHeadingMatch = remainingContent.match(/^#{1,6}\s+/m);
+    const endIndex = nextHeadingMatch ? nextHeadingMatch.index : 500;
+    const section = remainingContent.slice(0, endIndex);
+
+    // Parse for list items: "- name: description" or "- name - description"
+    const listItemPattern = /^[-*]\s+`?([^:`\n-]+)`?\s*[:\-]\s*(.+)$/gm;
+    let itemMatch;
+
+    while ((itemMatch = listItemPattern.exec(section)) !== null) {
+      const name = itemMatch[1].trim();
+      const description = itemMatch[2].trim();
+
+      if (name && description) {
+        items.push({
+          name,
+          type: 'api',
+          description,
+          example: null
+        });
+      }
+    }
+
+    // If we found items, we can stop searching
+    if (items.length > 0) {
+      break;
+    }
+
+    // If no list items found, create single item from section text
+    if (items.length === 0 && section.trim()) {
+      const sectionText = section.trim().split('\n')[0]; // First line
+      if (sectionText && sectionText.length > 10) {
+        items.push({
+          name: 'API',
+          type: 'api',
+          description: sectionText.slice(0, 200),
+          example: null
+        });
+      }
+    }
+  }
+
+  return items;
+}
+
+/**
+ * Calculate confidence score based on sources used
+ *
+ * Confidence levels:
+ * - 1.0: exports found
+ * - 0.8: bin found (no exports)
+ * - 0.6: README API section found (no exports/bin)
+ * - 0.3: partial data from multiple sources
+ * - 0.1: only "unknown" fallback
+ *
+ * @param {string[]} sources - Array of source names
+ * @returns {number} Confidence score between 0 and 1
+ *
+ * @example
+ * calculateConfidence(['exports', 'readme']) // => 1.0
+ * calculateConfidence(['bin']) // => 0.8
+ * calculateConfidence(['inferred']) // => 0.1
+ */
+function calculateConfidence(sources) {
+  // Fallback case
+  if (sources.includes('inferred')) {
+    return 0.1;
+  }
+
+  // Exports found (highest confidence)
+  if (sources.includes('exports')) {
+    return 1.0;
+  }
+
+  // Bin found (high confidence for CLI tools)
+  if (sources.includes('bin')) {
+    return 0.8;
+  }
+
+  // README API section found
+  if (sources.includes('readme')) {
+    return 0.6;
+  }
+
+  // Partial data (multiple sources but none of the above)
+  if (sources.length > 1) {
+    return 0.3;
+  }
+
+  // Default low confidence
+  return 0.2;
+}