@unrdf/diataxis-kit 26.4.2

package/test/fixtures/test-artifacts/ARTIFACTS/diataxis/test-pkg-3.inventory.json

@@ -0,0 +1,97 @@
+{
+  "packageName": "@unrdf/test-pkg-3",
+  "version": "2.1.0",
+  "generatedAt": "2025-01-01T00:00:00.000Z",
+  "confidence": {
+    "tutorials": 0.6,
+    "howtos": 0.7,
+    "reference": 0.8,
+    "explanation": 0.65
+  },
+  "tutorials": [
+    {
+      "id": "tutorial-start",
+      "title": "Start Here",
+      "goal": "Get started",
+      "prerequisites": [],
+      "stepsOutline": [
+        "Install",
+        "Use"
+      ],
+      "confidenceScore": 0.6,
+      "source": [
+        "readme"
+      ]
+    }
+  ],
+  "howtos": [
+    {
+      "id": "howto-config",
+      "title": "Configure",
+      "task": "Configure",
+      "context": "Setup",
+      "steps": [
+        "Edit config"
+      ],
+      "confidenceScore": 0.7,
+      "source": [
+        "readme"
+      ]
+    },
+    {
+      "id": "howto-integrate",
+      "title": "Integrate",
+      "task": "Integrate",
+      "context": "Integration",
+      "steps": [
+        "Setup"
+      ],
+      "confidenceScore": 0.7,
+      "source": [
+        "keywords"
+      ]
+    }
+  ],
+  "reference": {
+    "id": "reference-api",
+    "title": "API Reference",
+    "items": [
+      {
+        "name": "export1",
+        "type": "export",
+        "description": "Export",
+        "example": "import"
+      }
+    ],
+    "confidenceScore": 0.8,
+    "source": [
+      "exports"
+    ]
+  },
+  "explanation": {
+    "id": "explanation-overview",
+    "title": "Understanding Package",
+    "concepts": [
+      "concept"
+    ],
+    "architecture": "Architecture description",
+    "tradeoffs": [
+      "Tradeoff"
+    ],
+    "confidenceScore": 0.65,
+    "source": [
+      "readme"
+    ]
+  },
+  "evidence": {
+    "readmeHeadings": [
+      "Getting Started",
+      "Usage"
+    ],
+    "docsFiles": [],
+    "examplesFiles": [
+      "example.mjs"
+    ],
+    "fingerprint": "ghi789"
+  }
+}

package/test/fixtures/test-package/LICENSE

@@ -0,0 +1 @@
+MIT License

package/test/fixtures/test-package/README.md

@@ -0,0 +1,15 @@
+# Test Package
+
+This is a test package.
+
+## Installation
+
+Install with npm.
+
+## Usage
+
+Use the package like this.
+
+## API Reference
+
+See the API docs.

package/test/fixtures/test-package/docs/guide.md

@@ -0,0 +1,3 @@
+# User Guide
+
+This guide explains how to use the test package.

package/test/fixtures/test-package/examples/basic.mjs

@@ -0,0 +1,3 @@
+import { testFunction } from '../src/index.mjs';
+
+console.log(testFunction());

package/test/fixtures/test-package/src/index.mjs

@@ -0,0 +1,3 @@
+export function testFunction() {
+  return 'test';
+}

package/test/inventory.test.mjs

@@ -0,0 +1,199 @@
+/**
+ * @file Inventory discovery tests
+ * @description Validates package discovery and validation functions
+ */
+
+import assert from 'node:assert/strict';
+import { resolve } from 'node:path';
+import { discoverPackages, validatePackageEntry } from '../src/inventory.mjs';
+import { existsSync } from 'node:fs';
+
+let passCount = 0;
+let failCount = 0;
+
+/**
+ * Test runner
+ * @param {string} name - Test name
+ * @param {Function} fn - Async test function
+ */
+async function test(name, fn) {
+  try {
+    await fn();
+    console.log(`✅ ${name}`);
+    passCount++;
+  } catch (err) {
+    console.log(`❌ ${name}: ${err.message}`);
+    if (err.stack && process.env.VERBOSE) {
+      console.log(err.stack);
+    }
+    failCount++;
+  }
+}
+
+/**
+ * Test: discoverPackages finds at least 42 packages
+ */
+async function testDiscoverPackagesCount() {
+  const workspaceRoot = resolve(process.cwd(), '../..');
+  const packages = await discoverPackages(workspaceRoot);
+
+  if (packages.length < 42) {
+    throw new Error(`Expected >= 42 packages, found ${packages.length}`);
+  }
+
+  console.log(`  Found ${packages.length} packages`);
+}
+
+/**
+ * Test: All packages have required fields
+ */
+async function testRequiredFields() {
+  const workspaceRoot = resolve(process.cwd(), '../..');
+  const packages = await discoverPackages(workspaceRoot);
+
+  const requiredFields = ['name', 'dir', 'version', 'description'];
+  const missingFields = [];
+
+  for (const pkg of packages) {
+    for (const field of requiredFields) {
+      if (typeof pkg[field] !== 'string') {
+        missingFields.push(`${pkg.name || 'unknown'}: missing or invalid field '${field}'`);
+      }
+    }
+  }
+
+  if (missingFields.length > 0) {
+    throw new Error(`Missing fields:\n${missingFields.join('\n')}`);
+  }
+
+  console.log(`  Verified required fields for ${packages.length} packages`);
+}
+
+/**
+ * Test: Package names are unique
+ */
+async function testUniqueNames() {
+  const workspaceRoot = resolve(process.cwd(), '../..');
+  const packages = await discoverPackages(workspaceRoot);
+
+  const nameSet = new Set();
+  const duplicates = [];
+
+  for (const pkg of packages) {
+    if (nameSet.has(pkg.name)) {
+      duplicates.push(pkg.name);
+    }
+    nameSet.add(pkg.name);
+  }
+
+  if (duplicates.length > 0) {
+    throw new Error(`Duplicate package names: ${duplicates.join(', ')}`);
+  }
+
+  console.log(`  Verified ${packages.length} unique package names`);
+}
+
+/**
+ * Test: All package directories exist and are readable
+ */
+async function testDirectoriesExist() {
+  const workspaceRoot = resolve(process.cwd(), '../..');
+  const packages = await discoverPackages(workspaceRoot);
+
+  const missingDirs = [];
+
+  for (const pkg of packages) {
+    if (!existsSync(pkg.dir)) {
+      missingDirs.push(`${pkg.name}: directory not found at ${pkg.dir}`);
+    }
+  }
+
+  if (missingDirs.length > 0) {
+    throw new Error(`Missing directories:\n${missingDirs.join('\n')}`);
+  }
+
+  console.log(`  Verified all ${packages.length} directories exist`);
+}
+
+/**
+ * Test: validatePackageEntry works correctly
+ */
+async function testValidatePackageEntry() {
+  const workspaceRoot = resolve(process.cwd(), '../..');
+  const packages = await discoverPackages(workspaceRoot);
+
+  const validationErrors = [];
+
+  for (const pkg of packages) {
+    const result = validatePackageEntry(pkg);
+    if (!result.valid) {
+      validationErrors.push(`${pkg.name}: ${result.errors.join(', ')}`);
+    }
+  }
+
+  if (validationErrors.length > 0) {
+    throw new Error(`Validation errors:\n${validationErrors.join('\n')}`);
+  }
+
+  console.log(`  Validated ${packages.length} package entries`);
+}
+
+/**
+ * Test: Invalid entries are rejected
+ */
+async function testValidateRejectsInvalid() {
+  const invalidEntries = [
+    null,
+    undefined,
+    {},
+    { name: 'test' }, // Missing required fields
+    { name: 'test', dir: '/path', version: 123 }, // Wrong type
+    { name: 'test', dir: '/path', version: '1.0.0', description: 'test', exports: null }, // Invalid exports
+  ];
+
+  for (const entry of invalidEntries) {
+    const result = validatePackageEntry(entry);
+    if (result.valid) {
+      throw new Error(`Expected validation to fail for: ${JSON.stringify(entry)}`);
+    }
+  }
+
+  console.log(`  Verified validation rejects ${invalidEntries.length} invalid entries`);
+}
+
+/**
+ * Test: Packages are sorted by name
+ */
+async function testPackagesSorted() {
+  const workspaceRoot = resolve(process.cwd(), '../..');
+  const packages = await discoverPackages(workspaceRoot);
+
+  const names = packages.map(p => p.name);
+  const sortedNames = [...names].sort((a, b) => a.localeCompare(b));
+
+  for (let i = 0; i < names.length; i++) {
+    if (names[i] !== sortedNames[i]) {
+      throw new Error(`Packages not sorted: ${names[i]} at index ${i}, expected ${sortedNames[i]}`);
+    }
+  }
+
+  console.log(`  Verified ${packages.length} packages sorted alphabetically`);
+}
+
+// Run all tests
+async function runTests() {
+  console.log('Running inventory tests...\n');
+
+  await test('inventory: discovers >= 42 packages', testDiscoverPackagesCount);
+  await test('inventory: all packages have required fields', testRequiredFields);
+  await test('inventory: package names are unique', testUniqueNames);
+  await test('inventory: all directories exist', testDirectoriesExist);
+  await test('inventory: validatePackageEntry accepts valid entries', testValidatePackageEntry);
+  await test('inventory: validatePackageEntry rejects invalid entries', testValidateRejectsInvalid);
+  await test('inventory: packages sorted by name', testPackagesSorted);
+
+  console.log(`\n${passCount}/${passCount + failCount} tests passed`);
+  process.exit(failCount > 0 ? 1 : 0);
+}
+
+runTests();

package/test/reference-extractor.test.mjs

@@ -0,0 +1,187 @@
+/**
+ * @fileoverview Tests for reference-extractor.mjs
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { extractReference } from '../src/reference-extractor.mjs';
+
+describe('extractReference', () => {
+  it('should extract from exports field (string)', () => {
+    const pkg = {
+      name: 'test-pkg',
+      exports: './index.js'
+    };
+    const evidence = { readme: '' };
+
+    const result = extractReference(pkg, evidence);
+
+    assert.equal(result.id, 'reference');
+    assert.equal(result.title, 'test-pkg API Reference');
+    assert.equal(result.items.length, 1);
+    assert.equal(result.items[0].name, '.');
+    assert.equal(result.items[0].type, 'export');
+    assert.equal(result.items[0].description, './index.js');
+    assert.equal(result.confidenceScore, 1.0);
+    assert.deepEqual(result.source, ['exports']);
+  });
+
+  it('should extract from exports field (object)', () => {
+    const pkg = {
+      name: 'test-pkg',
+      exports: {
+        '.': './index.js',
+        './utils': './utils.js'
+      }
+    };
+    const evidence = { readme: '' };
+
+    const result = extractReference(pkg, evidence);
+
+    assert.equal(result.items.length, 2);
+    assert.equal(result.items[0].name, '.');
+    assert.equal(result.items[1].name, './utils');
+    assert.equal(result.confidenceScore, 1.0);
+  });
+
+  it('should extract from bin field (string)', () => {
+    const pkg = {
+      name: 'cli-tool',
+      bin: './cli.js'
+    };
+    const evidence = { readme: '' };
+
+    const result = extractReference(pkg, evidence);
+
+    assert.equal(result.items.length, 1);
+    assert.equal(result.items[0].name, 'cli-tool');
+    assert.equal(result.items[0].type, 'bin');
+    assert.ok(result.items[0].description.includes('CLI entry point'));
+    assert.equal(result.confidenceScore, 0.8);
+    assert.deepEqual(result.source, ['bin']);
+  });
+
+  it('should extract from bin field (object)', () => {
+    const pkg = {
+      name: 'multi-cli',
+      bin: {
+        'cmd1': './cmd1.js',
+        'cmd2': './cmd2.js'
+      }
+    };
+    const evidence = { readme: '' };
+
+    const result = extractReference(pkg, evidence);
+
+    assert.equal(result.items.length, 2);
+    assert.equal(result.items[0].name, 'cmd1');
+    assert.equal(result.items[1].name, 'cmd2');
+    assert.equal(result.confidenceScore, 0.8);
+  });
+
+  it('should extract from README API section', () => {
+    const pkg = { name: 'readme-pkg' };
+    const evidence = {
+      readme: `
+# Package
+
+## API
+
+- foo: Does something cool
+- bar: Does another thing
+      `
+    };
+
+    const result = extractReference(pkg, evidence);
+
+    assert.equal(result.items.length, 2);
+    assert.equal(result.items[0].name, 'bar');
+    assert.equal(result.items[0].type, 'api');
+    assert.equal(result.items[0].description, 'Does another thing');
+    assert.equal(result.items[1].name, 'foo');
+    assert.equal(result.confidenceScore, 0.6);
+    assert.deepEqual(result.source, ['readme']);
+  });
+
+  it('should combine multiple sources', () => {
+    const pkg = {
+      name: 'combo-pkg',
+      exports: { '.': './index.js' },
+      bin: './cli.js'
+    };
+    const evidence = {
+      readme: '## API\n\n- method: A method'
+    };
+
+    const result = extractReference(pkg, evidence);
+
+    assert.ok(result.items.length >= 3);
+    assert.equal(result.confidenceScore, 1.0); // exports = highest
+    assert.ok(result.source.includes('exports'));
+    assert.ok(result.source.includes('bin'));
+    assert.ok(result.source.includes('readme'));
+  });
+
+  it('should return unknown fallback when no data found', () => {
+    const pkg = { name: 'empty-pkg' };
+    const evidence = { readme: '' };
+
+    const result = extractReference(pkg, evidence);
+
+    assert.equal(result.items.length, 1);
+    assert.equal(result.items[0].name, 'unknown');
+    assert.equal(result.items[0].type, 'unknown');
+    assert.equal(result.items[0].description, 'API reference not found in documentation');
+    assert.equal(result.confidenceScore, 0.1);
+    assert.deepEqual(result.source, ['inferred']);
+  });
+
+  it('should sort items by name deterministically', () => {
+    const pkg = {
+      name: 'sort-test',
+      exports: {
+        './zebra': './z.js',
+        './alpha': './a.js',
+        './beta': './b.js'
+      }
+    };
+    const evidence = { readme: '' };
+
+    const result = extractReference(pkg, evidence);
+
+    assert.equal(result.items[0].name, './alpha');
+    assert.equal(result.items[1].name, './beta');
+    assert.equal(result.items[2].name, './zebra');
+  });
+
+  it('should handle conditional exports', () => {
+    const pkg = {
+      name: 'conditional-pkg',
+      exports: {
+        '.': {
+          import: './esm/index.js',
+          require: './cjs/index.js'
+        }
+      }
+    };
+    const evidence = { readme: '' };
+
+    const result = extractReference(pkg, evidence);
+
+    assert.equal(result.items.length, 1);
+    assert.equal(result.items[0].description, './esm/index.js'); // import first
+  });
+
+  it('should handle README with backticks in method names', () => {
+    const pkg = { name: 'backtick-pkg' };
+    const evidence = {
+      readme: '## Methods\n\n- `createStore()`: Creates a new store\n- `query()`: Runs a query'
+    };
+
+    const result = extractReference(pkg, evidence);
+
+    assert.equal(result.items.length, 2);
+    assert.equal(result.items[0].name, 'createStore()');
+    assert.equal(result.items[1].name, 'query()');
+  });
+});