Merge pull request #41 from wai-coding/dev

docs: rewrite README with deploy link and AI-assisted development section

Author: wai-coding

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## v8 — Post-Deploy Polish and AI-Assisted Development
+
+- Rewrote README with live demo link, architecture overview, and AI-assisted development section
+- Improved milestone summary generator with concrete bullet templates and stronger vague-phrase filtering
+- Fixed next milestone suggestions to exclude already-shipped features like web app deployment
+- Optimized browser bundle by separating React into its own vendor chunk alongside the existing analysis-engine chunk
+- Updated documentation across architecture, worklog, and code walkthrough for deploy-readiness consistency
+
 ## v7 — Deploy Polish and Browser Separation
 
 - Improved browser bundle architecture with a separate browser-safe entry point and lazy-loaded analysis engine

README.md

@@ -1,18 +1,22 @@
 # InspectoRepo – Project Context
 
-InspectoRepo is a local developer tool that analyzes TypeScript and React codebases and generates structured code review suggestions.
+InspectoRepo is a TypeScript code analysis tool that runs entirely in the browser. It analyzes TypeScript and React codebases and generates structured code review suggestions with proposed fixes.
+
+Live demo: https://inspectorepo.vercel.app
 
 Primary goals:
 
 - recruiter-impressive portfolio project
 - demonstrate TypeScript AST analysis
 - professional VSCode-like UI
 - export clean markdown reports
+- explore AI-assisted development workflows
 
 Tech stack:
 Frontend: React + TypeScript + Vite
 Analysis engine: ts-morph
 Testing: Vitest
+Deploy: Vercel
 
 Target users:
 
@@ -21,6 +25,7 @@ Target users:
 
 Constraints:
 
-- must run locally
+- runs in the browser — no server-side processing
 - no paid APIs
 - deterministic analysis
+- all code stays client-side

ai/project-context.md

@@ -149,18 +149,18 @@ function categorizeFiles(files: string[]): Map<string, string[]> {
 
 // Polished, outcome-focused bullet templates per area (≥8 words, verb-first, complete sentences)
 const AREA_BULLET_TEMPLATES: Record<string, string> = {
-  core: 'Expanded rule coverage with stronger detection accuracy and richer diagnostics.',
-  cli: 'Enhanced the command-line interface for a smoother developer experience.',
-  shared: 'Refined shared type definitions to improve cross-package type safety.',
-  'vscode-extension': 'Improved the VS Code extension for faster in-editor feedback.',
-  web: 'Polished the web interface for a more intuitive analysis workflow.',
-  docs: 'Updated documentation to reflect the latest codebase improvements and conventions.',
-  ai: 'Strengthened the export workflow so summaries are cleaner and more reliable.',
-  workflow: 'Improved the CI pipeline to catch more issues before code ships.',
-  examples: 'Updated example fixtures to demonstrate current rule coverage and patterns.',
-  screenshots: 'Refreshed screenshots and demo automation for accurate visual documentation.',
-  root: 'Aligned root project configuration with the current Node and TypeScript targets.',
-  other: 'Tightened build and lint settings to reduce drift across packages.',
+  core: 'Introduced a browser-safe entry point to prevent heavy analysis dependencies from entering the web bundle.',
+  cli: 'Strengthened the command-line fixer with detailed skip reporting and preview output.',
+  shared: 'Refined shared type definitions to eliminate redundant casts across packages.',
+  'vscode-extension': 'Improved the VS Code extension to auto-open reports after analysis completes.',
+  web: 'Improved the onboarding experience with clearer sample-project entry points and browser detection.',
+  docs: 'Clarified architecture documentation to reflect the browser-safe import separation.',
+  ai: 'Hardened the milestone summary generator with stricter bullet validation and vague-phrase rejection.',
+  workflow: 'Added automated InspectoRepo analysis as a GitHub Actions check on every pull request.',
+  examples: 'Expanded fixture files to trigger all fourteen implemented analysis rules.',
+  screenshots: 'Automated screenshot capture with Playwright for consistent visual documentation.',
+  root: 'Pinned the Node.js engine version to stabilize Vercel deployments.',
+  other: 'Strengthened rule-system validation tests to prevent configuration drift.',
 };
 
 // Banned patterns — bullets containing any of these are considered noisy/internal
@@ -285,13 +285,21 @@ function formatGroupedFiles(files: string[]): string {
 
 // Vague phrases that are banned from Human Summary bullets
 const VAGUE_BANNED_PHRASES: RegExp[] = [
-  /overall developer workflow configuration quality/i,
+  /overall developer workflow/i,
+  /configuration quality/i,
   /workspace consistency/i,
   /project tooling(?! \w)/i,
   /general improvements/i,
   /various fixes/i,
   /miscellaneous updates/i,
   /minor tweaks/i,
+  /code quality improvements/i,
+  /overall improvements/i,
+  /developer experience improvements/i,
+  /codebase improvements/i,
+  /several enhancements/i,
+  /multiple updates/i,
+  /routine maintenance/i,
 ];
 
 /** Check whether a bullet meets quality standards for human-readable output. */
@@ -325,7 +333,7 @@ function hasWebChanges(files: string[]): boolean {
   return files.some(f => f.startsWith('apps/web/'));
 }
 
-const DEPLOY_READINESS_BULLET = 'Improved deploy readiness in the web application with clearer onboarding and browser capability detection.'
+const DEPLOY_READINESS_BULLET = 'Polished the web application for public deployment with privacy-safe in-browser analysis and clearer onboarding.';
 
 /** Validate that all bullets pass quality rules. Returns list of failing bullets. */
 function validateBullets(bullets: string[]): string[] {
@@ -413,9 +421,9 @@ function generateHumanSummary(pr: PRInfo, files: string[], _commits: string): st
     bullets = buildAreaBullets(files);
     // Always ensure at least 3
     const fallbacks = [
-      'Strengthened the export workflow so summaries are cleaner and more reliable.',
-      'Updated documentation to reflect the latest codebase improvements and conventions.',
-      'Improved developer feedback with clearer diagnostics and auto-fix reporting.',
+      'Hardened the milestone summary generator with stricter bullet validation and vague-phrase rejection.',
+      'Clarified architecture documentation to reflect the browser-safe import separation.',
+      'Strengthened rule-system validation tests to prevent configuration drift.',
     ];
     for (const fb of fallbacks) {
       if (bullets.length >= 3) break;
@@ -580,9 +588,11 @@ const ROADMAP: RoadmapItem[] = [
   { label: 'Richer complexity warnings with contributor breakdown', implemented: true },
   { label: 'Conservative analysis rules (no-debugger, no-empty-catch, no-useless-return, ts-diagnostics)', implemented: true },
   { label: 'Additional conservative rules (no-console, no-empty-function, duplicate-imports, no-unreachable-after-return, no-throw-literal)', implemented: true },
-  { label: 'Deploy web app as a hosted service', implemented: false },
-  { label: 'Rule dependency graph and cascade analysis', implemented: false },
-  { label: 'Performance profiling for large codebases', implemented: false },
+  { label: 'Deploy web app as a hosted service', implemented: true },
+  { label: 'Additional safe rules for common anti-patterns like magic numbers and nested callbacks', implemented: false },
+  { label: 'Deeper analysis diagnostics with cross-file dependency tracking', implemented: false },
+  { label: 'Performance profiling and optimization for large monorepo codebases', implemented: false },
+  { label: 'Optional server-side analysis endpoint for CI integration without Node dependencies', implemented: false },
   { label: 'VS Code extension inline fix suggestions', implemented: false },
 ];
 
@@ -594,8 +604,8 @@ function generateNextMilestoneSection(): string {
   const items = unique.slice(0, 4);
   if (items.length < 2) {
     // Safety fallback — should never happen if ROADMAP is maintained
-    items.push('Explore additional static analysis rules');
-    items.push('Performance profiling for large codebases');
+    items.push('Additional safe rules for common anti-patterns');
+    items.push('Performance profiling for large monorepo codebases');
   }
 
   return items.map(i => `- ${i}`).join('\n');
@@ -685,9 +695,9 @@ if (bulletErrors.length > 0) {
   humanBullets = buildAreaBullets(milestoneFiles);
   // Ensure 3–5 range
   const fallbacks = [
-    'Strengthened the export workflow so summaries are cleaner and more reliable.',
-    'Updated documentation to reflect the latest codebase improvements and conventions.',
-    'Improved developer feedback with clearer diagnostics and auto-fix reporting.',
+    'Hardened the milestone summary generator with stricter bullet validation and vague-phrase rejection.',
+    'Clarified architecture documentation to reflect the browser-safe import separation.',
+    'Strengthened rule-system validation tests to prevent configuration drift.',
   ];
   for (const fb of fallbacks) {
     if (humanBullets.length >= 3) break;

ai/scripts/generate-repomix-exports.ts

@@ -8,6 +8,7 @@ export default defineConfig({
     rollupOptions: {
       output: {
         manualChunks: {
+          'react-vendor': ['react', 'react-dom'],
           'analysis-engine': ['@inspectorepo/core', 'ts-morph'],
         },
       },

apps/web/vite.config.ts

@@ -4,6 +4,37 @@ Development log for InspectoRepo. Each entry describes what was implemented, why
 
 ---
 
+## 2026-03-12 — V8: Post-Deploy Polish and AI-Assisted Development
+
+### What was implemented
+
+- **README rewrite** — replaced the original feature-list README with a recruiter-friendly version including: live demo link (https://inspectorepo.vercel.app), architecture overview, browser-safe bundle strategy, AI-assisted development section, and streamlined rules/CLI/configuration reference.
+- **Milestone summary generator improvements** — replaced vague area bullet templates with concrete, specific wording (e.g. "Introduced a browser-safe entry point to prevent heavy analysis dependencies from entering the web bundle"). Added 8 new vague-phrase bans including "code quality improvements", "overall improvements", and "developer experience improvements".
+- **Next milestone generator fix** — marked "Deploy web app as a hosted service" as implemented in the ROADMAP array. Replaced it with realistic future milestones: additional safe rules, deeper analysis diagnostics, performance optimization, and optional server-side analysis.
+- **Bundle optimization** — added `react-vendor` manual chunk to Vite config, separating React/ReactDOM from the main bundle for better caching alongside the existing `analysis-engine` chunk.
+- **Documentation consistency** — updated CHANGELOG, architecture docs, code walkthrough, and agent worklog to reflect deploy-readiness, browser-safe architecture, and AI-assisted development workflow.
+
+### Why
+
+After the first successful public deploy to Vercel, the README and documentation still described InspectoRepo as a local-only tool. The milestone summary generator produced vague bullets that wouldn't impress recruiters. The next milestone section incorrectly suggested deploying the web app — which was already done.
+
+### How to verify
+
+```bash
+npm run lint
+npm run typecheck
+npm run build
+npm test
+```
+
+### Design decisions
+
+- **README structure follows recruiter scanning patterns** — Live Demo near the top, Key Features as a scannable list, Architecture as a clear diagram. Technical details (CLI, configuration) come later.
+- **AI-assisted development section uses professional tone** — describes the workflow factually without hype, acknowledging both AI strengths and the need for human oversight.
+- **Concrete bullet templates** — each area template now describes a specific architectural improvement rather than a generic "improved X for better Y" pattern.
+
+---
+
 ## 2026-03-11 — V7: Deploy Polish and Browser Separation
 
 ### What was implemented

docs/agent-worklog.md

@@ -15,14 +15,26 @@ packages/core/src/
 ├── analyzer.ts           # analyzeCodebase() — main pipeline entry point
 ├── scoring.ts            # computeScore(issues) → { score, bySeverity }
 ├── report.ts             # buildMarkdownReport(AnalysisReport) → string
+├── report-parser.ts      # parseReportSummary(markdown) → ReportSummary
+├── custom-rule.ts        # defineRule() — custom rule authoring API
+├── presets.ts            # Rule preset system (recommended, strict, cleanup, react)
 ├── rule.ts               # Rule interface definition
 └── rules/
-    ├── index.ts           # Registry: allRules array
+    ├── index.ts                    # Registry: allRules array (14 rules)
     ├── unused-imports.ts
     ├── complexity-hotspot.ts
     ├── optional-chaining.ts
     ├── boolean-simplification.ts
-    └── early-return.ts
+    ├── early-return.ts
+    ├── no-debugger.ts
+    ├── no-empty-catch.ts
+    ├── no-useless-return.ts
+    ├── ts-diagnostics.ts
+    ├── no-console.ts
+    ├── no-empty-function.ts
+    ├── duplicate-imports.ts
+    ├── no-unreachable-after-return.ts
+    └── no-throw-literal.ts
 ```
 
 ### Key decisions

docs/architecture-and-rules.md

@@ -2,6 +2,8 @@
 
 A guided tour of the InspectoRepo codebase. Organized by package and file, with short explanations and snippets.
 
+The web app is deployed at https://inspectorepo.vercel.app and runs entirely in the browser. The analysis engine (ts-morph) is lazy-loaded to keep the initial page load fast. This project was built using AI-assisted development with GitHub Copilot agents inside VS Code.
+
 ---
 
 ## Root Configuration