Summary

This PR adds missingComplexTypeInfo field to ApiStats to track complex types (objects, interfaces, compound types) that are missing descriptions. These types are particularly important to document because their structure isn't self-explanatory.

Before / After Example

Given these TypeScript types:

/** User preferences for the application. */
export interface UserPreferences {
  theme: 'light' | 'dark';
  language: string;
}

export interface SearchOptions {   // <-- No description!
  query: string;
  filters: FilterSpec;
}

export type FilterSpec = {         // <-- No description!
  field: string;
  operator: 'eq' | 'neq';
};

export const DEFAULT_TIMEOUT = 5000;  // Simple type, not complex

Before this PR:

All undocumented items were lumped together in missingComments, making it hard to prioritize:

{
  "counts": {
    "missingComments": 4
  },
  "missingComments": [
    { "label": "SearchOptions", "type": "Interface" },
    { "label": "query", "type": "string" },
    { "label": "FilterSpec", "type": "Object" },
    { "label": "DEFAULT_TIMEOUT", "type": "number" }
  ]
}
// No way to identify which items are complex types needing priority!

After this PR:

Complex types are tracked separately for prioritized documentation efforts:

{
  "counts": {
    "missingComments": 4,
    "missingComplexTypeInfo": 2  // ✅ Complex types flagged separately!
  },
  "missingComplexTypeInfo": [
    {
      "id": "def-public.SearchOptions",
      "label": "SearchOptions",
      "type": "Interface",      // ✅ Interface - complex!
      "lineNumber": 6
    },
    {
      "id": "def-public.FilterSpec",
      "label": "FilterSpec",
      "type": "Object",         // ✅ Object - complex!
      "lineNumber": 11
    }
    // UserPreferences NOT flagged (has description)
    // DEFAULT_TIMEOUT NOT flagged (not a complex type)
  ]
}

What Counts as "Complex"?

Why This Matters

Complex types are the highest-value documentation targets:

• Simple types like string or number are self-documenting
• But interface SearchOptions with 5 properties? Readers need context
• Union types like 'eq' | 'neq' | 'gt' | 'lt' need explanation of what each value means

Changes

• Add trackMissingComplexTypeInfo function in stats.ts to detect and collect these issues during API stat collection
• Update check_package_docs_cli.ts to include missingComplexTypeInfo in the comments validation check
• Update mocks, fixture expected issue comments, and snapshot counts to reflect the new tracking

Impact

• Test plugin shows 22 complex types missing descriptions
• Validation integrated with --check comments flag in check_package_docs