@esthernandez/vibe-doc 0.1.0

package/dist/gap-analyzer/breadcrumbs.js

@@ -0,0 +1,314 @@
+"use strict";
+/**
+ * Breadcrumbs Module
+ * Search heuristics for finding evidence of documentation in artifacts
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBreadcrumbs = getBreadcrumbs;
+const logger_1 = require("../utils/logger");
+/**
+ * Get breadcrumbs for a specific doc type
+ */
+function getBreadcrumbs(docType) {
+    const breadcrumbs = {
+        adr: {
+            docType: 'adr',
+            keywords: [
+                'decision',
+                'architecture',
+                'trade-off',
+                'rationale',
+                'consequence',
+                'alternative',
+                'context',
+                'status',
+            ],
+            filePatterns: ['**/docs/adr/**', '**/adr/**', '**/decisions/**', '**/ADR*.md'],
+            gitPatterns: ['adr:', 'arch:', 'decision:'],
+            codePatterns: ['ADR', 'architecture decision', 'trade-off', 'rationale'],
+            requiredSections: [
+                'status',
+                'context',
+                'decision',
+                'consequences',
+                'alternatives',
+            ],
+            gapQuestions: [
+                'What major architectural decisions have you made?',
+                'What trade-offs did you consider and reject?',
+                'What were the alternatives to your current architecture?',
+            ],
+        },
+        runbook: {
+            docType: 'runbook',
+            keywords: [
+                'restart',
+                'rollback',
+                'deploy',
+                'monitor',
+                'health check',
+                'incident',
+                'on-call',
+                'procedure',
+                'emergency',
+                'escalation',
+            ],
+            filePatterns: [
+                '**/docs/runbooks/**',
+                '**/runbook/**',
+                '**/ops/**',
+                '**/RUNBOOK*.md',
+            ],
+            gitPatterns: ['fix:', 'hotfix:', 'revert:', 'ops:'],
+            codePatterns: [
+                'healthCheck',
+                'gracefulShutdown',
+                'process.exit',
+                'retry',
+                'circuitBreaker',
+                'liveness',
+            ],
+            requiredSections: [
+                'service-overview',
+                'startup-procedure',
+                'health-checks',
+                'common-issues',
+                'rollback-procedure',
+                'escalation-path',
+            ],
+            gapQuestions: [
+                'What is the process for restarting the service?',
+                'Who gets paged when something breaks?',
+                'What is your rollback procedure?',
+                'What are the most common issues and fixes?',
+            ],
+        },
+        'threat-model': {
+            docType: 'threat-model',
+            keywords: [
+                'threat',
+                'risk',
+                'vulnerability',
+                'attack',
+                'security',
+                'mitigation',
+                'trust boundary',
+                'adversary',
+                'exploit',
+            ],
+            filePatterns: ['**/docs/security/**', '**/threat/**', '**/THREAT*.md'],
+            gitPatterns: ['security:', 'vuln:', 'risk:'],
+            codePatterns: [
+                'authenticate',
+                'authorize',
+                'encrypt',
+                'sanitize',
+                'validate',
+                'csrf',
+                'xss',
+            ],
+            requiredSections: [
+                'asset-scope',
+                'threat-actors',
+                'threat-scenarios',
+                'mitigations',
+                'residual-risks',
+            ],
+            gapQuestions: [
+                'What are your most valuable assets that need protection?',
+                'What types of attacks are you most concerned about?',
+                'How do you authenticate users and services?',
+                'What encryption and secrets management do you use?',
+            ],
+        },
+        'api-spec': {
+            docType: 'api-spec',
+            keywords: [
+                'endpoint',
+                'request',
+                'response',
+                'parameter',
+                'authentication',
+                'error',
+                'status code',
+                'schema',
+            ],
+            filePatterns: [
+                '**/swagger.json',
+                '**/openapi.yaml',
+                '**/docs/api/**',
+                '**/API*.md',
+            ],
+            gitPatterns: ['api:', 'endpoint:'],
+            codePatterns: [
+                '@route',
+                '@get',
+                '@post',
+                '@put',
+                '@delete',
+                'router.get',
+                'app.post',
+            ],
+            requiredSections: [
+                'base-url',
+                'endpoints',
+                'request-format',
+                'response-format',
+                'error-handling',
+                'authentication',
+            ],
+            gapQuestions: [
+                'What are your primary API endpoints?',
+                'What request/response formats do you use?',
+                'How do you handle authentication and authorization?',
+                'What error codes and messages do you return?',
+            ],
+        },
+        'deployment-procedure': {
+            docType: 'deployment-procedure',
+            keywords: [
+                'deploy',
+                'release',
+                'build',
+                'pipeline',
+                'ci/cd',
+                'environment',
+                'staging',
+                'production',
+                'rollback',
+            ],
+            filePatterns: [
+                '**/.github/workflows/**',
+                '**/deploy/**',
+                '**/docs/deployment/**',
+                '**/DEPLOY*.md',
+            ],
+            gitPatterns: ['deploy:', 'release:', 'ci:'],
+            codePatterns: [
+                'docker build',
+                'kubectl apply',
+                'terraform apply',
+                'database migration',
+            ],
+            requiredSections: [
+                'prerequisites',
+                'build-process',
+                'environment-setup',
+                'testing-before-deploy',
+                'deployment-steps',
+                'post-deployment-checks',
+                'rollback-procedure',
+            ],
+            gapQuestions: [
+                'What is your build process?',
+                'How do you deploy to different environments?',
+                'What tests run before deployment?',
+                'How do you handle database migrations?',
+                'What is your rollback procedure?',
+            ],
+        },
+        'test-plan': {
+            docType: 'test-plan',
+            keywords: [
+                'test',
+                'unit',
+                'integration',
+                'e2e',
+                'coverage',
+                'quality',
+                'testing strategy',
+                'acceptance criteria',
+            ],
+            filePatterns: [
+                '**/*.test.ts',
+                '**/*.spec.ts',
+                '**/test/**',
+                '**/tests/**',
+                '**/TEST*.md',
+            ],
+            gitPatterns: ['test:', 'fix:', 'test-fix:'],
+            codePatterns: [
+                'describe',
+                'it(',
+                'test(',
+                'expect',
+                'assert',
+                'mock',
+                'stub',
+            ],
+            requiredSections: [
+                'test-strategy',
+                'unit-tests',
+                'integration-tests',
+                'e2e-tests',
+                'performance-tests',
+                'coverage-targets',
+            ],
+            gapQuestions: [
+                'What is your testing strategy?',
+                'What is your code coverage target?',
+                'What critical paths do you test end-to-end?',
+                'How do you test performance?',
+                'How do you test third-party integrations?',
+            ],
+        },
+        'data-model': {
+            docType: 'data-model',
+            keywords: [
+                'schema',
+                'table',
+                'column',
+                'entity',
+                'relationship',
+                'constraint',
+                'index',
+                'type',
+                'field',
+            ],
+            filePatterns: [
+                '**/migrations/**',
+                '**/schema/**',
+                '**/models/**',
+                '**/DATA*.md',
+            ],
+            gitPatterns: ['schema:', 'model:', 'migrate:'],
+            codePatterns: [
+                'CREATE TABLE',
+                'ALTER TABLE',
+                'interface',
+                'type',
+                '@entity',
+                '@model',
+            ],
+            requiredSections: [
+                'entity-overview',
+                'table-schemas',
+                'relationships',
+                'constraints',
+                'indexes',
+                'migration-strategy',
+            ],
+            gapQuestions: [
+                'What are your main entities/tables?',
+                'What are the relationships between them?',
+                'What constraints and validation rules exist?',
+                'How do you handle schema migrations?',
+                'What indexing strategy do you use?',
+            ],
+        },
+    };
+    const breadcrumb = breadcrumbs[docType];
+    if (!breadcrumb) {
+        logger_1.logger.warn('Unknown doc type for breadcrumbs', { docType });
+        return {
+            docType,
+            keywords: [],
+            filePatterns: [],
+            gitPatterns: [],
+            codePatterns: [],
+            requiredSections: [],
+            gapQuestions: [],
+        };
+    }
+    return breadcrumb;
+}

package/dist/gap-analyzer/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Gap Analyzer Orchestrator
+ * Main entry point for documentation gap analysis
+ */
+import { ArtifactInventory, Classification, GapReport } from '../state/schema';
+/**
+ * Analyze documentation gaps based on classification
+ */
+export declare function analyzeGaps(classification: Classification, inventory: ArtifactInventory): GapReport;
+export { getRequiredDocs } from './matrix';
+export { getBreadcrumbs } from './breadcrumbs';
+export { assessGaps } from './tier-assigner';
+//# sourceMappingURL=index.d.ts.map

package/dist/gap-analyzer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/gap-analyzer/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,SAAS,EAAW,MAAM,iBAAiB,CAAC;AAMxF;;GAEG;AACH,wBAAgB,WAAW,CACzB,cAAc,EAAE,cAAc,EAC9B,SAAS,EAAE,iBAAiB,GAC3B,SAAS,CA0CX;AAwCD,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/gap-analyzer/index.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * Gap Analyzer Orchestrator
+ * Main entry point for documentation gap analysis
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assessGaps = exports.getBreadcrumbs = exports.getRequiredDocs = void 0;
+exports.analyzeGaps = analyzeGaps;
+const logger_1 = require("../utils/logger");
+const matrix_1 = require("./matrix");
+const breadcrumbs_1 = require("./breadcrumbs");
+const tier_assigner_1 = require("./tier-assigner");
+/**
+ * Analyze documentation gaps based on classification
+ */
+function analyzeGaps(classification, inventory) {
+    logger_1.logger.info('Starting gap analysis', {
+        category: classification.primaryCategory,
+        contexts: classification.contextModifiers,
+    });
+    // Step 1: Get required docs for this classification
+    const contexts = classification.contextModifiers;
+    const requirements = (0, matrix_1.getRequiredDocs)(classification.primaryCategory, contexts);
+    // Step 2: Get breadcrumbs for all doc types
+    const breadcrumbsMap = new Map();
+    const docTypes = new Set(requirements.map((r) => r.docType));
+    for (const docType of docTypes) {
+        breadcrumbsMap.set(docType, (0, breadcrumbs_1.getBreadcrumbs)(docType));
+    }
+    // Step 3: Run tier assigner to assess gaps
+    const gaps = (0, tier_assigner_1.assessGaps)(requirements, inventory, breadcrumbsMap);
+    // Step 4: Calculate summary statistics
+    const summary = calculateSummary(gaps, inventory);
+    logger_1.logger.info('Gap analysis complete', {
+        totalGaps: gaps.length,
+        coveragePercent: summary.coveragePercent,
+        docsMissing: summary.docsMissing,
+    });
+    return {
+        summary,
+        gaps: gaps.map((gap) => ({
+            docType: gap.docType,
+            tier: gap.tier,
+            domain: classification.primaryCategory,
+            artifactsScanned: gap.artifactsScanned,
+            found: gap.found,
+            missing: gap.missing,
+            rationale: gap.rationale,
+        })),
+    };
+}
+/**
+ * Calculate summary statistics from gaps
+ */
+function calculateSummary(gaps, inventory) {
+    const totalArtifacts = inventory.totalArtifacts;
+    let docsCovered = 0; // Docs with all sections found
+    let docsPartial = 0; // Docs with some sections found
+    let docsMissing = 0; // Docs with no sections found
+    for (const gap of gaps) {
+        if (gap.found === 0) {
+            docsMissing++;
+        }
+        else if (gap.missing === 0) {
+            docsCovered++;
+        }
+        else {
+            docsPartial++;
+        }
+    }
+    const totalRequiredDocs = gaps.length;
+    const coveragePercent = totalRequiredDocs > 0
+        ? Math.round(((docsCovered + docsPartial * 0.5) / totalRequiredDocs) * 100)
+        : 0;
+    return {
+        totalArtifacts,
+        docsCovered,
+        docsPartial,
+        docsMissing,
+        coveragePercent,
+    };
+}
+var matrix_2 = require("./matrix");
+Object.defineProperty(exports, "getRequiredDocs", { enumerable: true, get: function () { return matrix_2.getRequiredDocs; } });
+var breadcrumbs_2 = require("./breadcrumbs");
+Object.defineProperty(exports, "getBreadcrumbs", { enumerable: true, get: function () { return breadcrumbs_2.getBreadcrumbs; } });
+var tier_assigner_2 = require("./tier-assigner");
+Object.defineProperty(exports, "assessGaps", { enumerable: true, get: function () { return tier_assigner_2.assessGaps; } });

package/dist/gap-analyzer/matrix.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Documentation Matrix
+ * Defines required documentation types per category x context
+ */
+export declare enum DocType {
+    ADR = "adr",
+    Runbook = "runbook",
+    ThreatModel = "threat-model",
+    APISpec = "api-spec",
+    DeploymentProcedure = "deployment-procedure",
+    TestPlan = "test-plan",
+    DataModel = "data-model"
+}
+export declare enum Tier {
+    Required = "required",
+    Recommended = "recommended",
+    Optional = "optional"
+}
+export interface DocRequirement {
+    docType: DocType;
+    tier: Tier;
+    category: string;
+    contexts: string[];
+}
+/**
+ * Get required documentation types for a category and contexts
+ */
+export declare function getRequiredDocs(category: string, contexts: string[]): DocRequirement[];
+//# sourceMappingURL=matrix.d.ts.map

package/dist/gap-analyzer/matrix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix.d.ts","sourceRoot":"","sources":["../../src/gap-analyzer/matrix.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,oBAAY,OAAO;IACjB,GAAG,QAAQ;IACX,OAAO,YAAY;IACnB,WAAW,iBAAiB;IAC5B,OAAO,aAAa;IACpB,mBAAmB,yBAAyB;IAC5C,QAAQ,cAAc;IACtB,SAAS,eAAe;CACzB;AAED,oBAAY,IAAI;IACd,QAAQ,aAAa;IACrB,WAAW,gBAAgB;IAC3B,QAAQ,aAAa;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAuED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAAE,GACjB,cAAc,EAAE,CAmDlB"}

package/dist/gap-analyzer/matrix.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * Documentation Matrix
+ * Defines required documentation types per category x context
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tier = exports.DocType = void 0;
+exports.getRequiredDocs = getRequiredDocs;
+const logger_1 = require("../utils/logger");
+var DocType;
+(function (DocType) {
+    DocType["ADR"] = "adr";
+    DocType["Runbook"] = "runbook";
+    DocType["ThreatModel"] = "threat-model";
+    DocType["APISpec"] = "api-spec";
+    DocType["DeploymentProcedure"] = "deployment-procedure";
+    DocType["TestPlan"] = "test-plan";
+    DocType["DataModel"] = "data-model";
+})(DocType || (exports.DocType = DocType = {}));
+var Tier;
+(function (Tier) {
+    Tier["Required"] = "required";
+    Tier["Recommended"] = "recommended";
+    Tier["Optional"] = "optional";
+})(Tier || (exports.Tier = Tier = {}));
+/**
+ * Base tier assignments per category
+ */
+const BASE_MATRIX = {
+    [DocType.ADR]: {
+        WebApplication: Tier.Recommended,
+        APIMicroservice: Tier.Recommended,
+        DataPipeline: Tier.Recommended,
+        InfrastructurePlatform: Tier.Recommended,
+        MobileApplication: Tier.Recommended,
+        AIMLSystem: Tier.Recommended,
+        IntegrationConnector: Tier.Recommended,
+    },
+    [DocType.Runbook]: {
+        WebApplication: Tier.Required,
+        APIMicroservice: Tier.Required,
+        DataPipeline: Tier.Required,
+        InfrastructurePlatform: Tier.Required,
+        MobileApplication: Tier.Required,
+        AIMLSystem: Tier.Required,
+        IntegrationConnector: Tier.Recommended,
+    },
+    [DocType.ThreatModel]: {
+        WebApplication: Tier.Recommended,
+        APIMicroservice: Tier.Required,
+        DataPipeline: Tier.Recommended,
+        InfrastructurePlatform: Tier.Recommended,
+        MobileApplication: Tier.Required,
+        AIMLSystem: Tier.Required,
+        IntegrationConnector: Tier.Recommended,
+    },
+    [DocType.APISpec]: {
+        WebApplication: Tier.Required,
+        APIMicroservice: Tier.Required,
+        DataPipeline: Tier.Optional,
+        InfrastructurePlatform: Tier.Optional,
+        MobileApplication: Tier.Recommended,
+        AIMLSystem: Tier.Recommended,
+        IntegrationConnector: Tier.Required,
+    },
+    [DocType.DeploymentProcedure]: {
+        WebApplication: Tier.Required,
+        APIMicroservice: Tier.Required,
+        DataPipeline: Tier.Required,
+        InfrastructurePlatform: Tier.Required,
+        MobileApplication: Tier.Required,
+        AIMLSystem: Tier.Required,
+        IntegrationConnector: Tier.Recommended,
+    },
+    [DocType.TestPlan]: {
+        WebApplication: Tier.Recommended,
+        APIMicroservice: Tier.Recommended,
+        DataPipeline: Tier.Required,
+        InfrastructurePlatform: Tier.Recommended,
+        MobileApplication: Tier.Required,
+        AIMLSystem: Tier.Required,
+        IntegrationConnector: Tier.Recommended,
+    },
+    [DocType.DataModel]: {
+        WebApplication: Tier.Required,
+        APIMicroservice: Tier.Recommended,
+        DataPipeline: Tier.Required,
+        InfrastructurePlatform: Tier.Optional,
+        MobileApplication: Tier.Recommended,
+        AIMLSystem: Tier.Required,
+        IntegrationConnector: Tier.Optional,
+    },
+};
+/**
+ * Get required documentation types for a category and contexts
+ */
+function getRequiredDocs(category, contexts) {
+    const requirements = [];
+    for (const docType of Object.values(DocType)) {
+        let tier = BASE_MATRIX[docType][category] || Tier.Optional;
+        // Apply context modifiers
+        if (contexts.includes('Regulated')) {
+            // Security-related docs to Required for regulated
+            if (docType === DocType.ThreatModel ||
+                docType === DocType.DeploymentProcedure ||
+                docType === DocType.ADR) {
+                tier = Tier.Required;
+            }
+        }
+        if (contexts.includes('CustomerFacing')) {
+            // Customer-facing requires ops and quality docs
+            if (docType === DocType.Runbook ||
+                docType === DocType.APISpec ||
+                docType === DocType.TestPlan) {
+                tier = Tier.Required;
+            }
+        }
+        if (contexts.includes('MultiTenant')) {
+            // MultiTenant requires security and data model docs
+            if (docType === DocType.ThreatModel || docType === DocType.DataModel) {
+                tier = Tier.Required;
+            }
+        }
+        requirements.push({
+            docType,
+            tier,
+            category,
+            contexts,
+        });
+    }
+    logger_1.logger.info('Required docs retrieved', {
+        category,
+        contextCount: contexts.length,
+        docCount: requirements.length,
+    });
+    return requirements;
+}

package/dist/gap-analyzer/tier-assigner.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Tier Assigner Module
+ * Assesses gaps based on breadcrumb searches and requirement analysis
+ */
+import { ArtifactInventory } from '../state/schema';
+import { DocRequirement, Tier } from './matrix';
+import { Breadcrumb } from './breadcrumbs';
+export interface Gap {
+    docType: string;
+    tier: Tier;
+    category: string;
+    artifactsScanned: number;
+    found: number;
+    missing: number;
+    rationale: string;
+}
+/**
+ * Assess documentation gaps based on artifact inventory
+ */
+export declare function assessGaps(requirements: DocRequirement[], inventory: ArtifactInventory, breadcrumbs: Map<string, Breadcrumb>): Gap[];
+export { getBreadcrumbs } from './breadcrumbs';
+//# sourceMappingURL=tier-assigner.d.ts.map

package/dist/gap-analyzer/tier-assigner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tier-assigner.d.ts","sourceRoot":"","sources":["../../src/gap-analyzer/tier-assigner.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAkB,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3D,MAAM,WAAW,GAAG;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,YAAY,EAAE,cAAc,EAAE,EAC9B,SAAS,EAAE,iBAAiB,EAC5B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GACnC,GAAG,EAAE,CA+BP;AAmGD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}