Function auditComponent

scripts/docs-audit.ts:293–366

* Audits a single component by comparing source declarations against documentation.

(dirPath: string)

 * Audits a single component by comparing source declarations against documentation.
 */
function auditComponent(dirPath: string): ComponentAuditEntry {
  const dirName = path.basename(dirPath);
  const componentFilePath = path.join(dirPath, `${dirName}.component.ts`);

  // Extract source declarations
  const sourceInputs = extractInputs(componentFilePath);
  const sourceOutputs = extractOutputs(componentFilePath);

  // Find corresponding doc file
  const docFilePath = findDocFile(dirName);

  if (!docFilePath) {
    return {
      name: dirName,
      status: 'missing',
      docFile: null,
      sourceInputs,
      sourceOutputs,
      documentedInputs: [],
      documentedOutputs: [],
      missingInputs: sourceInputs,
      missingOutputs: sourceOutputs,
      staleInputs: [],
      staleOutputs: [],
    };
  }

  const relativeDocPath = path.relative(process.cwd(), docFilePath);

  // Extract documented entries
  const documentedInputs = extractDocumentedInputs(docFilePath);
  const documentedOutputs = extractDocumentedOutputs(docFilePath);

  // Find missing: in source but not in docs
  const missingInputs = sourceInputs.filter(
    (input) => !documentedInputs.includes(input)
  );
  const missingOutputs = sourceOutputs.filter(
    (output) => !documentedOutputs.includes(output)
  );

  // Find stale: in docs but not in source
  const staleInputs = documentedInputs.filter(
    (input) => !sourceInputs.includes(input)
  );
  const staleOutputs = documentedOutputs.filter(
    (output) => !sourceOutputs.includes(output)
  );

  // Classify status
  const hasGaps =
    missingInputs.length > 0 ||
    missingOutputs.length > 0 ||
    staleInputs.length > 0 ||
    staleOutputs.length > 0;

  const status: ComponentAuditEntry['status'] = hasGaps
    ? 'partially-documented'