sync-docs-analysis

# sync-docs-analysis

Analyze documentation for issues related to code changes.

## Input

Arguments: `<doc-path> <changed-file> [--deep]`

- **doc-path**: Path to the documentation file to analyze
- **changed-file**: The source file that changed
- **--deep**: Enable deep analysis (check code examples, verify imports)

## Analysis Types

### 1. Version References

Check if documentation references outdated versions.

```javascript
const { collectors } = require('@awesome-slash/lib');

const issues = collectors.docsPatterns.analyzeDocIssues(docPath, changedFile, {
  checkVersions: true
});
```

Detects:
- Package version mismatches
- API version references
- Changelog version mentions

### 2. Import/Export References

Check if documentation references removed or renamed exports.

```javascript
const exports = collectors.docsPatterns.getExportsFromGit(changedFile);
// Compare with doc content
```

Detects:
- References to removed functions
- Outdated import statements
- Renamed symbols

### 3. Code Examples

Check if code examples still work with current implementation.

```javascript
// Deep mode only
const examples = extractCodeBlocks(docContent);
for (const example of examples) {
  const imports = parseImports(example);
  const valid = validateImports(imports, currentExports);
}
```

Detects:
- Examples using removed APIs
- Examples with wrong import paths
- Examples with outdated patterns

### 4. File Path References

Check if file paths mentioned in docs still exist.

```javascript
const pathRefs = extractFilePaths(docContent);
for (const ref of pathRefs) {
  if (!fs.existsSync(ref)) {
    issues.push({ type: 'missing-file', path: ref });
  }
}
```

## Output Format

```json
{
  "doc": "README.md",
  "referencedFile": "src/utils.js",
  "issues": [
    {
      "type": "outdated-version",
      "line": 15,
      "current": "1.0.0",
      "expected": "1.1.0",
      "certainty": "HIGH",
      "autoFix": true,
      "suggestion": "Update version from 1.0.0 to 1.1.0"