Cache File Format Specification

{
  "version": "1.0.0",
  "generated_at": "2025-12-21T15:30:00Z",
  "git_commit": "abc123def456",
  "project": { },
  "stats": { },
  "source_files": { },
  "files": { },
  "symbols": { },
  "annotations": { },
  "graph": { },
  "domains": { },
  "constraints": { },
  "documentation": { },
  "provenance": { }
}

{
  "project": {
    "name": "my-project",
    "root": "/absolute/path/to/project",
    "description": "Optional project description"
  }
}

{
  "stats": {
    "files": 127,
    "symbols": 843,
    "lines": 24521
  }
}

{
  "source_files": {
    "src/auth/session.ts": "2024-12-17T15:29:00Z",
    "src/utils/helpers.ts": "2024-12-17T14:20:00Z"
  }
}

{
  "files": {
    "src/auth/session.ts": {
      "path": "src/auth/session.ts",
      "module": "Session Management",
      "summary": "Handles user session lifecycle and validation",
      "lines": 234,
      "language": "typescript",
      "domains": ["authentication"],
      "layer": "service",
      "stability": "stable",
      "exports": ["src/auth/session.ts:SessionService"],
      "imports": ["jsonwebtoken", "src/db/users"]
    }
  }
}

{
  "refs": [
    {
      "url": "https://react.dev/reference/react/hooks",
      "sourceId": "react",
      "version": "18.2",
      "section": "hooks/rules-of-hooks",
      "fetch": true,
      "scope": "file",
      "line": 5
    },
    {
      "url": "https://docs.company.com/api/auth",
      "sourceId": "company-api",
      "fetch": false,
      "scope": "symbol",
      "symbolName": "validateSession",
      "line": 45
    }
  ]
}

{
  "style": {
    "name": "company-react",
    "extends": "airbnb-react",
    "source": "company-api",
    "url": "https://docs.company.com/style",
    "rules": ["prefer-function-components", "max-line-length=120"],
    "scope": "file",
    "line": 3
  }
}

{
  "inline": [
    {
      "type": "critical",
      "line": 45,
      "directive": "Review with extreme care; errors here have severe consequences"
    },
    {
      "type": "todo",
      "value": "Add rate limiting",
      "line": 78,
      "directive": "This work is pending; consider completing before related changes",
      "ticket": "JIRA-123"
    },
    {
      "type": "fixme",
      "value": "Race condition",
      "line": 102,
      "directive": "Known issue that needs resolution; avoid relying on current behavior"
    }
  ]
}

{
  "annotations": {
    "summary": {
      "value": "Session management utilities",
      "source": "heuristic",
      "confidence": 0.82,
      "needsReview": false,
      "reviewed": true,
      "reviewedAt": "2025-01-15T10:30:00Z",
      "generatedAt": "2025-01-10T14:22:00Z",
      "generationId": "gen-20250110-001"
    },
    "domain": {
      "value": "authentication",
      "source": "heuristic",
      "confidence": 0.75,
      "needsReview": true,
      "reviewed": false,
      "generatedAt": "2025-01-10T14:22:00Z",
      "generationId": "gen-20250110-001"
    }
  }
}

{
  "path": "src/utils/helpers.ts",
  "lines": 45,
  "language": "typescript",
  "exports": [],
  "imports": []
}

{
  "path": "src/auth/session.ts",
  "module": "Session Management",
  "summary": "Handles user session lifecycle and validation",
  "lines": 234,
  "language": "typescript",
  "domains": ["authentication", "security"],
  "layer": "service",
  "stability": "stable",
  "exports": [
    "src/auth/session.ts:SessionService",
    "src/auth/session.ts:SessionService.validateSession"
  ],
  "imports": [
    "jsonwebtoken",
    "redis",
    "src/db/users",
    "src/utils/crypto"
  ]
}

{
  "symbols": {
    "src/auth/session.ts:SessionService.validateSession": {
      "name": "validateSession",
      "qualified_name": "src/auth/session.ts:SessionService.validateSession",
      "type": "method",
      "file": "src/auth/session.ts",
      "lines": [45, 89],
      "signature": "(token: string) => Promise<Session | null>",
      "summary": "Validates JWT token and returns session",
      "async": true,
      "exported": true,
      "visibility": "public",
      "calls": [
        "src/auth/jwt.ts:verifyToken",
        "src/db/sessions.ts:findSession"
      ],
      "called_by": [
        "src/api/middleware.ts:authMiddleware"
      ]
    }
  }
}

{
  "params": [
    {
      "name": "token",
      "description": "JWT token string",
      "directive": "Ensure token is a valid JWT string before calling"
    }
  ],
  "returns": {
    "description": "Session object or null if invalid",
    "directive": "Handle null case appropriately in calling code"
  },
  "throws": [
    {
      "exception": "AuthError",
      "description": "When token is malformed",
      "directive": "Handle AuthError appropriately when calling"
    }
  ],
  "constraints": {
    "lock_level": "frozen",
    "lock_reason": "Core authentication logic",
    "directive": "MUST NOT modify this function under any circumstances"
  }
}

{relative_path}:{qualified_symbol}

{
  "name": "formatDate",
  "qualified_name": "src/utils/helpers.ts:formatDate",
  "type": "function",
  "file": "src/utils/helpers.ts",
  "lines": [12, 15],
  "signature": "(date: Date) => string",
  "summary": "Formats date to ISO 8601 string",
  "exported": true,
  "visibility": "public"
}

{
  "name": "validateSession",
  "qualified_name": "src/auth/session.ts:SessionService.validateSession",
  "type": "method",
  "file": "src/auth/session.ts",
  "lines": [45, 89],
  "signature": "(token: string) => Promise<Session | null>",
  "summary": "Validates JWT token and returns session",
  "async": true,
  "exported": true,
  "visibility": "public",
  "calls": [
    "src/auth/jwt.ts:verifyToken",
    "src/db/sessions.ts:findSession"
  ],
  "called_by": [
    "src/api/middleware.ts:authMiddleware"
  ]
}

{
  "graph": {
    "forward": {
      "src/auth/session.ts:SessionService.validateSession": [
        "src/auth/jwt.ts:verifyToken",
        "src/db/sessions.ts:findSession"
      ],
      "src/api/middleware.ts:authMiddleware": [
        "src/auth/session.ts:SessionService.validateSession"
      ]
    },
    "reverse": {
      "src/auth/jwt.ts:verifyToken": [
        "src/auth/session.ts:SessionService.validateSession"
      ],
      "src/auth/session.ts:SessionService.validateSession": [
        "src/api/middleware.ts:authMiddleware"
      ]
    }
  }
}

{
  "domains": {
    "authentication": {
      "name": "authentication",
      "description": "User authentication and session management",
      "files": [
        "src/auth/session.ts",
        "src/auth/jwt.ts",
        "src/auth/middleware.ts"
      ],
      "symbols": [
        "src/auth/session.ts:SessionService.validateSession",
        "src/auth/jwt.ts:generateToken",
        "src/auth/middleware.ts:authMiddleware"
      ]
    }
  }
}

{
  "constraints": {
    "by_file": {
      "src/auth/session.ts": {
        "lock_level": "restricted",
        "lock_reason": "Security critical",
        "style": "google-typescript"
      }
    },
    "by_lock_level": {
      "frozen": ["src/config/production.ts"],
      "restricted": ["src/auth/session.ts"]
    }
  }
}

{
  "by_file": {
    "src/auth/session.ts": {
      "lock_level": "restricted",
      "lock_reason": "Security-critical code",
      "directive": "Explain proposed changes and wait for explicit approval before modifying",
      "style": "google-typescript",
      "behavior": "conservative",
      "quality": ["security-review", "tests-required"],
      "auto_generated": false
    }
  }
}

{
  "documentation": {
    "sources": {
      "react": {
        "url": "https://react.dev/reference",
        "version": "18.2",
        "fileCount": 15,
        "files": ["src/components/UserProfile.tsx", "src/hooks/useAuth.ts"]
      },
      "company-api": {
        "url": "https://docs.company.com/api",
        "version": null,
        "fileCount": 8,
        "files": ["src/api/auth.ts", "src/api/users.ts"]
      }
    },
    "styles": {
      "google-typescript": {
        "fileCount": 42,
        "files": ["src/utils/helpers.ts"],
        "source": null
      },
      "company-react": {
        "fileCount": 15,
        "files": ["src/components/UserProfile.tsx"],
        "source": "company-api"
      }
    },
    "unresolvedRefs": [
      {
        "file": "src/legacy/old.ts",
        "ref": "deprecated-api",
        "reason": "Source ID not found in approved sources"
      }
    ]
  }
}

{
  "provenance": {
    "summary": {
      "total": 150,
      "bySource": {
        "explicit": 80,
        "converted": 20,
        "heuristic": 45,
        "refined": 5,
        "inferred": 0
      },
      "needsReview": 12,
      "reviewed": 58,
      "averageConfidence": {
        "converted": 0.92,
        "heuristic": 0.76
      }
    },
    "lowConfidence": [
      {
        "target": "src/utils/helpers.ts",
        "annotation": "domain",
        "confidence": 0.45,
        "value": "utility"
      }
    ],
    "lastGeneration": {
      "id": "gen-20251222-001",
      "timestamp": "2025-12-22T10:30:00Z",
      "annotationsGenerated": 25,
      "filesAffected": 8
    }
  }
}

FUNCTION generateCache(projectRoot, config):
    cache = initializeCache(projectRoot, config)
    files = discoverFiles(projectRoot, config)
 
    FOR each file IN files:
        fileEntry = indexFile(file)
        cache.files[file.path] = fileEntry
 
        symbols = extractSymbols(file)
        FOR each symbol IN symbols:
            cache.symbols[symbol.qualified_name] = symbol
            updateGraph(cache.graph, symbol)
 
    cache.domains = buildDomainIndex(cache.files)
    cache.constraints = buildConstraintIndex(cache.files, cache.symbols)
    cache.stats = calculateStats(cache)
 
    RETURN cache

ajv validate -s https://acp-spec.org/schemas/v1/cache.schema.json -d .acp.cache.json

{
  "version": "1.0.0",
  "generated_at": "2024-12-17T15:30:00Z",
  "git_commit": "abc123def456",
  "project": {
    "name": "auth-service",
    "root": "/home/user/projects/auth-service",
    "description": "Authentication microservice"
  },
  "stats": {
    "files": 3,
    "symbols": 2,
    "lines": 270
  },
  "source_files": {
    "src/auth/session.ts": "2024-12-17T15:29:00Z",
    "src/auth/jwt.ts": "2024-12-17T15:20:00Z"
  },
  "files": {
    "src/auth/session.ts": {
      "path": "src/auth/session.ts",
      "module": "Session Service",
      "summary": "User session management",
      "lines": 245,
      "language": "typescript",
      "domains": ["authentication"],
      "layer": "service",
      "stability": "stable",
      "exports": [
        "src/auth/session.ts:SessionService",
        "src/auth/session.ts:SessionService.validateSession"
      ],
      "imports": ["jsonwebtoken", "src/auth/jwt"]
    }
  },
  "symbols": {
    "src/auth/session.ts:SessionService.validateSession": {
      "name": "validateSession",
      "qualified_name": "src/auth/session.ts:SessionService.validateSession",
      "type": "method",
      "file": "src/auth/session.ts",
      "lines": [45, 89],
      "signature": "(token: string) => Promise<Session | null>",
      "summary": "Validates JWT and returns session",
      "exported": true,
      "async": true,
      "calls": ["src/auth/jwt.ts:verifyToken"],
      "called_by": []
    }
  },
  "graph": {
    "forward": {
      "src/auth/session.ts:SessionService.validateSession": [
        "src/auth/jwt.ts:verifyToken"
      ]
    },
    "reverse": {
      "src/auth/jwt.ts:verifyToken": [
        "src/auth/session.ts:SessionService.validateSession"
      ]
    }
  },
  "domains": {
    "authentication": {
      "name": "authentication",
      "description": "User authentication and session management",
      "files": ["src/auth/session.ts"],
      "symbols": ["src/auth/session.ts:SessionService.validateSession"]
    }
  },
  "constraints": {
    "by_file": {
      "src/auth/session.ts": {
        "lock_level": "restricted",
        "lock_reason": "Security critical",
        "style": "google-typescript"
      }
    },
    "by_lock_level": {
      "restricted": ["src/auth/session.ts"]
    }
  }
}

# Get all files
jq '.files | keys' .acp.cache.json
 
# Get symbol by name
jq '.symbols["src/auth/session.ts:SessionService.validateSession"]' .acp.cache.json
 
# Get all restricted files
jq '.constraints.by_lock_level.restricted' .acp.cache.json
 
# Get callers of a function
jq '.graph.reverse["src/auth/session.ts:SessionService.validateSession"]' .acp.cache.json
 
# Get files in a domain
jq '.domains["authentication"].files' .acp.cache.json
 
# Check if file can be modified
jq '.constraints.by_file["src/auth/session.ts"].lock_level' .acp.cache.json
 
# Get all TypeScript files
jq '.files | to_entries | map(select(.value.language == "typescript")) | .[].key' .acp.cache.json
 
# Count symbols by type
jq '.symbols | to_entries | group_by(.value.type) | map({type: .[0].value.type, count: length})' .acp.cache.json