docit-ai 1.0.0

package/.env.example

@@ -0,0 +1 @@
+GEMINI_API_KEY=AIzaSyCRnvcYlB3rnQXLHtGp6DLqhOAlq4NQnX0

package/INSTRUCTIONS.MD

@@ -0,0 +1,70 @@
+1. Project Overview
+Docit is a CLI-first, npm-distributed tool that generates and automatically updates technical documentation for software projects. It is designed to be a high-performance, affordable alternative to Mintlify. It utilizes local parsing (AST) combined with cost-effective LLMs (Gemini 2.5 Flash-Lite) to keep token costs minimal.
+
+2. Core Architecture
+The IDE should assist in building these four modules:
+
+The Scanner: Uses simple-git to identify files modified in the last commit.
+
+The Parser: Uses tree-sitter to extract "Code Skeletons" (function names, parameters, return types, and comments) to reduce token usage.
+
+The Engine: Orchestrates calls to the LLM (Default: Gemini 2.5 Flash-Lite).
+
+The Formatter: Generates three distinct views of the documentation based on the target audience.
+
+3. Persona-Based Formatting Rules
+The IDE must implement a "View Controller" that formats the AI output into three distinct sections within the generated documentation:
+
+A. The "Strategic View" (For Project Managers)
+Focus: Business value and status.
+
+Format: High-level summaries, "What this feature enables," and a "Completeness Score" (0-100%).
+
+Style: No code snippets. Use bullet points and bold text for key deliverables.
+
+B. The "Technical View" (For Developers/Newbies)
+Focus: Architecture and integration.
+
+Format: Detailed function signatures, dependency maps, and "How to use" code examples.
+
+Style: Strict Markdown with syntax highlighting. Includes "Internal Logic" explanations.
+
+C. The "Personal View" (For Individuals/Solo Devs)
+Focus: Productivity and reminders.
+
+Format: A "To-Do" list generated from TODO comments in code and a "Technical Debt" summary.
+
+Style: Concise, checklist-style formatting.
+
+4. Technical Constraints for IDE Implementation
+Language: TypeScript (Strict Mode).
+
+Parsing: Use @tree-sitter/tree-sitter with language-specific grammars.
+
+AI Strategy: * Context Window Management: Do not send the whole file. Send only the AST "Skeleton."
+
+Caching: Check docit.lock (a JSON file) for file hashes. If the hash matches, skip the AI call.
+
+CLI: Use commander for the interface. Main command: docit sync.
+
+5. Immediate Tasks for the IDE
+Environment Sync: Create package.json with dependencies: simple-git, tree-sitter, tree-sitter-typescript, @google/genai, commander, dotenv.
+
+Parser Module: Implement src/parser/extractor.ts to find all ExportNamedDeclaration nodes in a TypeScript file.
+
+AI Module: Implement src/ai/prompts.ts containing the three system prompts for the PM, Dev, and Individual views.
+
+CLI Module: Create the docit sync command that ties these together.
+
+6. Target Documentation File Structure
+Docit should output to a file named DOCIT.md (or a /docs folder) with the following hierarchy:
+
+Project Overview
+
+PM Dashboard (Strategic View)
+
+Developer Reference (Technical View)
+
+Personal Roadmap (Individual View)
+
+Changelog (Auto-generated from Git history)

package/dist/ai/engine.d.ts

@@ -0,0 +1,24 @@
+import { type ViewType } from "./prompts.js";
+/**
+ * AI Engine Module
+ * Orchestrates calls to the Gemini LLM.
+ */
+export interface DocumentationResult {
+    view: ViewType;
+    content: string;
+}
+export interface EngineConfig {
+    apiKey: string;
+    model?: string | undefined;
+    maxRetries?: number | undefined;
+}
+export declare class DocitEngine {
+    private ai;
+    private model;
+    private maxRetries;
+    constructor(config: EngineConfig);
+    generateDocumentation(codeSkeleton: string, view: ViewType): Promise<DocumentationResult>;
+    generateAllViews(codeSkeleton: string): Promise<DocumentationResult[]>;
+}
+export declare function createEngine(apiKey: string): DocitEngine;
+//# sourceMappingURL=engine.d.ts.map

package/dist/ai/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/ai/engine.ts"],"names":[],"mappings":"AACA,OAAO,EAAoB,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE/D;;;GAGG;AAEH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAMD,qBAAa,WAAW;IACtB,OAAO,CAAC,EAAE,CAAc;IACxB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,UAAU,CAAS;gBAEf,MAAM,EAAE,YAAY;IAM1B,qBAAqB,CACzB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,QAAQ,GACb,OAAO,CAAC,mBAAmB,CAAC;IAiDzB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;CAY7E;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAExD"}

package/dist/ai/engine.js

@@ -0,0 +1,69 @@
+import { GoogleGenAI } from "@google/genai";
+import { getPromptForView } from "./prompts.js";
+async function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export class DocitEngine {
+    ai;
+    model;
+    maxRetries;
+    constructor(config) {
+        this.ai = new GoogleGenAI({ apiKey: config.apiKey });
+        this.model = config.model ?? "gemini-2.0-flash";
+        this.maxRetries = config.maxRetries ?? 5;
+    }
+    async generateDocumentation(codeSkeleton, view) {
+        const systemPrompt = getPromptForView(view);
+        let lastError;
+        for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+            try {
+                const response = await this.ai.models.generateContent({
+                    model: this.model,
+                    contents: [
+                        {
+                            role: "user",
+                            parts: [
+                                {
+                                    text: `${systemPrompt}\n\n---\n\nAnalyze the following code skeleton and generate documentation:\n\n${codeSkeleton}`,
+                                },
+                            ],
+                        },
+                    ],
+                });
+                const content = response.text ?? "";
+                return {
+                    view,
+                    content,
+                };
+            }
+            catch (error) {
+                lastError = error;
+                const status = error.status;
+                // Retry on 503 (overloaded) or 429 (rate limit)
+                if (status === 503 || status === 429) {
+                    const waitTime = Math.pow(2, attempt) * 1000; // Exponential backoff
+                    console.log(`   ⏳ Model overloaded, retrying in ${waitTime / 1000}s...`);
+                    await sleep(waitTime);
+                    continue;
+                }
+                // Don't retry other errors
+                throw error;
+            }
+        }
+        throw lastError ?? new Error("Max retries exceeded");
+    }
+    async generateAllViews(codeSkeleton) {
+        const views = ["strategic", "technical", "personal"];
+        const results = [];
+        for (const view of views) {
+            console.log(`   📄 Generating ${view} view...`);
+            const result = await this.generateDocumentation(codeSkeleton, view);
+            results.push(result);
+        }
+        return results;
+    }
+}
+export function createEngine(apiKey) {
+    return new DocitEngine({ apiKey });
+}
+//# sourceMappingURL=engine.js.map

package/dist/ai/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/ai/engine.ts"],"names":[],"mappings":"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"}

package/dist/ai/prompts.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AI Prompts Module
+ * Contains system prompts for the three persona-based views.
+ */
+export declare const STRATEGIC_VIEW_PROMPT = "You are a technical writer creating documentation for Project Managers.\n\nYour task is to analyze code skeletons and produce a \"Strategic View\" summary.\n\nRULES:\n- Focus on business value and project status\n- NO code snippets allowed\n- Use bullet points and bold text for key deliverables\n- Include a \"What this feature enables\" section\n- Provide a \"Completeness Score\" (0-100%) based on:\n  - Function implementation status\n  - TODO comments remaining\n  - Interface completeness\n\nOUTPUT FORMAT:\n## Feature: [Feature Name]\n\n**What This Enables:**\n- [Business capability 1]\n- [Business capability 2]\n\n**Status:**\n- **Completeness Score:** XX%\n- [Key status points]\n\n**Key Deliverables:**\n- [Deliverable 1]\n- [Deliverable 2]\n";
+export declare const TECHNICAL_VIEW_PROMPT = "You are a technical writer creating documentation for Developers.\n\nYour task is to analyze code skeletons and produce a \"Technical View\" reference.\n\nRULES:\n- Focus on architecture and integration details\n- Include detailed function signatures\n- Provide dependency maps where applicable\n- Include \"How to use\" code examples\n- Explain internal logic when relevant\n- Use strict Markdown with syntax highlighting\n\nOUTPUT FORMAT:\n## Module: [Module Name]\n\n### Overview\n[Brief description of the module's purpose]\n\n### Functions\n\n#### `functionName(params): returnType`\n**Description:** [What this function does]\n\n**Parameters:**\n- `param1` (Type): Description\n- `param2` (Type): Description\n\n**Returns:** Type - Description\n\n**Example:**\n```typescript\n// Usage example\n```\n\n### Dependencies\n- [Dependency 1]: [Purpose]\n- [Dependency 2]: [Purpose]\n\n### Internal Logic\n[Explanation of key algorithms or patterns]\n";
+export declare const PERSONAL_VIEW_PROMPT = "You are a technical writer creating documentation for Solo Developers.\n\nYour task is to analyze code skeletons and produce a \"Personal View\" roadmap.\n\nRULES:\n- Focus on productivity and actionable items\n- Generate a To-Do list from TODO comments in code\n- Create a \"Technical Debt\" summary\n- Use concise, checklist-style formatting\n- Prioritize items by importance\n\nOUTPUT FORMAT:\n## Personal Roadmap: [File/Module Name]\n\n### Action Items\n- [ ] [High Priority] Task from TODO comment\n- [ ] [Medium Priority] Improvement suggestion\n- [ ] [Low Priority] Nice-to-have enhancement\n\n### Technical Debt\n| Issue | Location | Effort | Impact |\n|-------|----------|--------|--------|\n| [Description] | Line X | Low/Med/High | Low/Med/High |\n\n### Quick Notes\n- [Notable patterns or concerns]\n- [Suggestions for refactoring]\n";
+export declare function getPromptForView(view: "strategic" | "technical" | "personal"): string;
+export declare const VIEWS: readonly ["strategic", "technical", "personal"];
+export type ViewType = (typeof VIEWS)[number];
+//# sourceMappingURL=prompts.d.ts.map

package/dist/ai/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../src/ai/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,qBAAqB,uvBA4BjC,CAAC;AAEF,eAAO,MAAM,qBAAqB,27BAwCjC,CAAC;AAEF,eAAO,MAAM,oBAAoB,k1BA2BhC,CAAC;AAEF,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,WAAW,GAAG,WAAW,GAAG,UAAU,GAC3C,MAAM,CAWR;AAED,eAAO,MAAM,KAAK,iDAAkD,CAAC;AACrE,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/ai/prompts.js

@@ -0,0 +1,116 @@
+/**
+ * AI Prompts Module
+ * Contains system prompts for the three persona-based views.
+ */
+export const STRATEGIC_VIEW_PROMPT = `You are a technical writer creating documentation for Project Managers.
+
+Your task is to analyze code skeletons and produce a "Strategic View" summary.
+
+RULES:
+- Focus on business value and project status
+- NO code snippets allowed
+- Use bullet points and bold text for key deliverables
+- Include a "What this feature enables" section
+- Provide a "Completeness Score" (0-100%) based on:
+  - Function implementation status
+  - TODO comments remaining
+  - Interface completeness
+
+OUTPUT FORMAT:
+## Feature: [Feature Name]
+
+**What This Enables:**
+- [Business capability 1]
+- [Business capability 2]
+
+**Status:**
+- **Completeness Score:** XX%
+- [Key status points]
+
+**Key Deliverables:**
+- [Deliverable 1]
+- [Deliverable 2]
+`;
+export const TECHNICAL_VIEW_PROMPT = `You are a technical writer creating documentation for Developers.
+
+Your task is to analyze code skeletons and produce a "Technical View" reference.
+
+RULES:
+- Focus on architecture and integration details
+- Include detailed function signatures
+- Provide dependency maps where applicable
+- Include "How to use" code examples
+- Explain internal logic when relevant
+- Use strict Markdown with syntax highlighting
+
+OUTPUT FORMAT:
+## Module: [Module Name]
+
+### Overview
+[Brief description of the module's purpose]
+
+### Functions
+
+#### \`functionName(params): returnType\`
+**Description:** [What this function does]
+
+**Parameters:**
+- \`param1\` (Type): Description
+- \`param2\` (Type): Description
+
+**Returns:** Type - Description
+
+**Example:**
+\`\`\`typescript
+// Usage example
+\`\`\`
+
+### Dependencies
+- [Dependency 1]: [Purpose]
+- [Dependency 2]: [Purpose]
+
+### Internal Logic
+[Explanation of key algorithms or patterns]
+`;
+export const PERSONAL_VIEW_PROMPT = `You are a technical writer creating documentation for Solo Developers.
+
+Your task is to analyze code skeletons and produce a "Personal View" roadmap.
+
+RULES:
+- Focus on productivity and actionable items
+- Generate a To-Do list from TODO comments in code
+- Create a "Technical Debt" summary
+- Use concise, checklist-style formatting
+- Prioritize items by importance
+
+OUTPUT FORMAT:
+## Personal Roadmap: [File/Module Name]
+
+### Action Items
+- [ ] [High Priority] Task from TODO comment
+- [ ] [Medium Priority] Improvement suggestion
+- [ ] [Low Priority] Nice-to-have enhancement
+
+### Technical Debt
+| Issue | Location | Effort | Impact |
+|-------|----------|--------|--------|
+| [Description] | Line X | Low/Med/High | Low/Med/High |
+
+### Quick Notes
+- [Notable patterns or concerns]
+- [Suggestions for refactoring]
+`;
+export function getPromptForView(view) {
+    switch (view) {
+        case "strategic":
+            return STRATEGIC_VIEW_PROMPT;
+        case "technical":
+            return TECHNICAL_VIEW_PROMPT;
+        case "personal":
+            return PERSONAL_VIEW_PROMPT;
+        default:
+            throw new Error(`Unknown view type: ${view}`);
+    }
+}
+export const VIEWS = ["strategic", "technical", "personal"];
+//# sourceMappingURL=prompts.js.map

package/dist/ai/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../src/ai/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BpC,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwCpC,CAAC;AAEF,MAAM,CAAC,MAAM,oBAAoB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BnC,CAAC;AAEF,MAAM,UAAU,gBAAgB,CAC9B,IAA4C;IAE5C,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,WAAW;YACd,OAAO,qBAAqB,CAAC;QAC/B,KAAK,WAAW;YACd,OAAO,qBAAqB,CAAC;QAC/B,KAAK,UAAU;YACb,OAAO,oBAAoB,CAAC;QAC9B;YACE,MAAM,IAAI,KAAK,CAAC,sBAAsB,IAAI,EAAE,CAAC,CAAC;IAClD,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,WAAW,EAAE,WAAW,EAAE,UAAU,CAAU,CAAC"}

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function createCli(): Command;
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAyKpC,wBAAgB,SAAS,IAAI,OAAO,CA8XnC"}