fullstack-critic 1.0.0

package/memory/templates/PROJECT_PROFILE.md

@@ -0,0 +1,45 @@
+# Project Profile
+
+<!-- Written by the AI on first REVIEW. Updated when architecture changes are confirmed. -->
+<!-- Never store credentials, tokens, API keys, PII, passwords, or raw log data here. -->
+
+## System
+
+- **Name:**
+- **Purpose:**
+- **Language:**
+- **Framework:**
+- **Database:**
+- **Cache:**
+- **Queue:**
+- **Auth mechanism:**
+- **Hosting / runtime:**
+- **CI/CD:**
+
+## Entry points
+
+<!--
+  Key files confirmed during the discovery layer.
+  - src/index.ts       — HTTP server
+  - src/routes.ts      — route registration
+-->
+
+## Architecture summary
+
+<!--
+  Short description of the request lifecycle, major services, and data flow.
+  Written after discovery layer. Updated only when evidence contradicts it.
+-->
+
+## Known constraints
+
+<!--
+  Hard limits discovered during review:
+  DB connection pool size, queue concurrency cap, external API rate limits, vendor SLAs.
+-->
+
+## Scale context
+
+- **Stated target:**
+- **Load test evidence:** none / see REVIEW_HISTORY.md entry YYYY-MM-DD
+- **Observed ceiling (if known):**

package/memory/templates/REVIEW_HISTORY.md

@@ -0,0 +1,24 @@
+# Review History
+
+<!-- One entry per completed session. Written at session end. -->
+<!-- Never store credentials, tokens, API keys, PII, passwords, or raw log data here. -->
+
+## Entry format
+
+```
+### YYYY-MM-DD — Session title
+
+- **Mode:** REVIEW | FIX | OPTIMIZE | CLEAN | VERIFY | FULL
+- **Layers loaded:** list
+- **Files read:** count
+- **Findings:** BLOCKER: 0  CRITICAL: 0  HIGH: 0  MEDIUM: 0  LOW: 0  INFO: 0
+- **Top finding:** One-line description of most severe confirmed issue
+- **Fixed this session:** yes / no — list changed files if yes
+- **Status:** open | in-progress | resolved
+- **Commit / PR:** hash or link if resolved
+- **Load test run:** yes / no — brief result if yes
+```
+
+---
+
+<!-- AI writes entries below this line -->

package/memory/templates/RUN_STATE.md

@@ -0,0 +1,40 @@
+# Run State
+
+<!-- Written at session start. Updated when layer switches. Reset each new session. -->
+<!-- Never store credentials, tokens, API keys, PII, passwords, or raw log data here. -->
+
+## Current session
+
+- **Started:** YYYY-MM-DD HH:MM UTC
+- **Mode:** REVIEW | FIX | OPTIMIZE | CLEAN | VERIFY | FULL
+- **Focus:** (from PROJECT_REVIEW.md or direct user request)
+- **Active layer:**
+- **Files currently loaded:**
+  <!--
+    List here — cleared on layer switch
+    - src/routes/checkout.ts
+    - src/middleware/auth.ts
+  -->
+
+## Layer history this session
+
+<!--
+  One line per completed layer — keeps a breadcrumb of what was already covered.
+  api — checkout route and payment middleware — 3 findings staged
+  backend — BookingService.reserve() — 1 finding staged
+-->
+
+## Staged findings
+
+<!--
+  Temporary. Move to final report before ending session.
+  SEVERITY | path/to/file:line | short description
+  CRITICAL | src/routes/checkout.ts:84 | payment amount trusted from client body
+-->
+
+## Pending layer switches
+
+<!--
+  Layers still required by evidence. Clear when loaded or ruled out.
+  database — required: N+1 suspected at src/services/product.ts:112
+-->

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "fullstack-critic",
+  "version": "1.0.0",
+  "description": "A free, universal principal-engineer critic. Attach it to any project or run it as a background watcher over any in-progress workflow. Reviews 100% of resources — code, packages, and dependencies — across 12 dimensions and emits an evidence-based report with a fix / optimize / delete / add action plan.",
+  "keywords": [
+    "code-review",
+    "critic",
+    "static-analysis",
+    "watcher",
+    "security",
+    "dependencies",
+    "quality",
+    "ci",
+    "ai"
+  ],
+  "license": "MIT",
+  "author": "amansingh79033-ship-it",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amansingh79033-ship-it/fullstack-critic.git"
+  },
+  "bin": {
+    "fullstack-critic": "bin/fullstack-critic.js",
+    "critic": "bin/fullstack-critic.js"
+  },
+  "main": "src/index.js",
+  "files": [
+    "bin",
+    "src",
+    "tests",
+    "CRITIC.md",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "GEMINI.md",
+    "PROJECT_REVIEW.md",
+    "agent",
+    "layers",
+    "memory",
+    "prompts",
+    "docs",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "review": "node bin/fullstack-critic.js review",
+    "watch": "node bin/fullstack-critic.js watch",
+    "audit": "node bin/fullstack-critic.js audit",
+    "test": "node --test tests/*.test.js",
+    "lint": "node -c bin/fullstack-critic.js && node --check src/cli.js",
+    "selftest": "node bin/fullstack-critic.js review . --json .critic-review.json"
+  },
+  "dependencies": {}
+}

package/prompts/composio-upgrade-agent.md

@@ -0,0 +1,299 @@
+# Composio Agent Prompt — Upgrade fullstack-critic to v2
+
+Paste this entire file into a Composio workspace agent.
+The agent will read the current repo state, apply all v2 upgrades, validate,
+and push to GitHub in a single commit — autonomously, without breaking any
+running session or workflow attached to the repo.
+
+---
+
+## Your identity
+
+You are a senior full-stack engineering agent in a Composio workspace.
+Work through every phase below in order. Report clearly after each phase.
+Do not ask for confirmation between phases unless a step is explicitly marked CONFIRM.
+Do not skip validation. Do not commit if validation fails.
+
+## Repository
+
+`amansingh79033-ship-it/fullstack-critic`
+
+---
+
+## Phase 1 — Read current state (no writes)
+
+1. `GITHUB_GET_REPOSITORY` → confirm access, note default branch and last commit SHA.
+2. `GITHUB_LIST_REPO_CONTENTS` on root → record every file and folder present.
+3. `GITHUB_GET_FILE_CONTENTS` for each of these files (capture SHA of each):
+   - `CRITIC.md`
+   - `CLAUDE.md`
+   - `GEMINI.md`
+   - `AGENTS.md`
+   - `README.md`
+   - `agent/fullstack-critic-agent.md`
+   - `layers/manifest.md`
+   - `prompts/composio-upgrade-agent.md` (if exists)
+   - `memory/templates/PROJECT_PROFILE.md` (if exists)
+   - `memory/templates/DECISIONS.md` (if exists)
+   - `memory/templates/REVIEW_HISTORY.md` (if exists)
+   - `memory/templates/RUN_STATE.md` (if exists)
+4. List what exists, what is missing, and what has content vs stubs.
+5. **Do not write anything yet.**
+
+---
+
+## Phase 2 — Apply upgrades
+
+For every file below, use `GITHUB_GET_FILE_CONTENTS` to get the current SHA
+(even if already read in Phase 1 — SHA may have changed).
+Then use `GITHUB_CREATE_OR_UPDATE_FILE_CONTENTS` with that SHA to write.
+For new files (not in Phase 1 listing), omit the SHA parameter.
+
+### 2.1 — CRITIC.md
+
+Replace with the universal v2 rubric. The file must contain:
+- A title: `Full-Stack Critic — Universal Engineering Standard`
+- A Modes table with 6 rows: REVIEW, FIX, OPTIMIZE, CLEAN, VERIFY, FULL
+- A "12 Dimensions" section with all 12 headings numbered 1–12:
+  1. Correctness and data integrity
+  2. Security
+  3. Architecture and design
+  4. API design
+  5. Backend and services
+  6. Database and persistence
+  7. Frontend and UI
+  8. Performance and scalability
+  9. Code quality and maintainability
+  10. Testing and observability
+  11. Deployment and infrastructure
+  12. Enterprise-grade practices
+- A "Non-negotiable rules" section
+- A "Report format" section with:
+  - Executive Summary table (12 rows + overall)
+  - Findings block using `### SEVERITY — Title` format (no pipe/bracket syntax)
+  - Fix Summary table
+  - Scalability Assessment
+  - Prioritised Action Plan table
+  - Final Verdict (4 choices)
+
+Do not include the broken `[BLOCKER|CRITICAL|HIGH|MEDIUM|LOW|INFO]` heading format.
+Use `### SEVERITY — Title` (em dash, not pipe) for finding headings.
+
+### 2.2 — CLAUDE.md
+
+Replace with content covering:
+- Read order: CRITIC.md → PROJECT_REVIEW.md → AGENTS.md
+- Zero-impact attach instructions (submodule + clone commands)
+- Claude Code tool discipline: Glob before read, Grep before file open,
+  Read with line ranges, never load build/vendor dirs
+- TodoWrite per finding, TodoRead before layer switch
+- Layer discipline: one layer at a time, 15-file cap, summarise before switch
+- FIX mode: smallest diff, state verification step, record in Fix Summary
+- Memory bootstrap from `memory/templates/`
+
+### 2.3 — GEMINI.md
+
+Replace with content covering:
+- Read order: CRITIC.md → PROJECT_REVIEW.md → AGENTS.md
+- Zero-impact attach instructions (submodule + clone commands + `@` usage)
+- Gemini CLI tool discipline: `@` references for layer files,
+  never read directories, use grep/find/rg first
+- Load priority when context constrained: Routes → Middleware → Schema → Service → Repository → Tests
+- Layer discipline: one layer, evidence required for second, scratchpad before switch
+- FIX mode: minimal unified diff, state exact verification command
+- Memory bootstrap from `memory/templates/`
+
+### 2.4 — AGENTS.md
+
+Replace with content covering:
+- What this tool is (one paragraph — free, universal, any AI, no setup)
+- Zero-impact attach instructions (submodule, clone, or copy minimum files)
+- Modes table with 6 rows and example commands per mode
+- Quick start section with copy-paste prompts for: generic, Claude Code, Gemini CLI, Composio
+- 8 rules that apply to every AI and every mode
+
+### 2.5 — agent/fullstack-critic-agent.md
+
+Update (preserve existing structure, apply these additions):
+- Add zero-impact attach instructions at the top
+- Add the 6-mode table from CRITIC.md
+- Update workflow to `READ → SELECT → IMPORT → WORK → STAGE → SUMMARISE → DISCARD → EXPORT → UPDATE`
+- Add validation step in COMPOSIO_REMOTE_WORKBENCH before every write
+- Add example requests for REVIEW, FIX, and FULL modes
+- Preserve all existing Composio tool names exactly as they are
+
+### 2.6 — layers/manifest.md
+
+Update the layer table to add these rows if not already present:
+- `api-client` — how a frontend or service calls an API
+- `auth` — authentication, authorisation, sessions, tokens
+- `architecture` — system design, module boundaries, dependency graph
+- `transactional` — orders, payments, reservations, inventory, state machines
+
+Update the dependency rules table to include:
+- `transactional` → `database`
+- `transactional` → `cache-queue`
+- `auth` → `api`
+- `auth` → `database`
+
+### 2.7 — layers/transactional-domain.md (new file)
+
+Create this file. Content must include:
+- Purpose statement (universal — e-commerce, SaaS, ticketing, booking, fintech)
+- Chunks to load table (7 rows)
+- Checks section with subsections: Idempotency, Atomicity and race conditions,
+  Payment flow, State machine integrity, Inventory and capacity,
+  Cancellation and refunds, Notifications and side effects
+- Extra report sections: Transactional Integrity Review, Payment Flow Review,
+  Inventory and Capacity Review, State Machine Review
+
+### 2.8 — PROJECT_REVIEW.md (new file at repo root)
+
+Create universal template. Fields required:
+- Project name and purpose (comment explaining it)
+- Tech stack table (Language, Framework, Database, Cache, Queue, Auth, Hosting, CI/CD, Monitoring)
+- Entry points (commented example)
+- Review mode (comment: REVIEW | FIX | OPTIMIZE | CLEAN | VERIFY | FULL)
+- Review focus (comment with specific and general examples)
+- Scale requirement (comment: write "unknown" not guesses)
+- Known risks (commented examples)
+- Out of scope (commented examples)
+- Prior incidents (commented example)
+- Load test status (comment explaining the AI will not claim targets without this)
+
+### 2.9 — memory/templates/ (4 files — create if missing, do not overwrite if content exists)
+
+Check each file. If it exists and has content beyond the header, skip it.
+If it is missing or empty, create it with:
+
+**PROJECT_PROFILE.md** — System fields, Entry points, Architecture summary, Known constraints, Scale context
+**DECISIONS.md** — Entry format block, divider, "AI writes below" comment
+**REVIEW_HISTORY.md** — Entry format block, divider, "AI writes below" comment
+**RUN_STATE.md** — Current session fields, Layer history section, Staged findings section, Pending layer switches section
+
+### 2.10 — prompts/composio-upgrade-agent.md
+
+Replace with the current contents of this file (this prompt itself, updated).
+This ensures the upgrade prompt is always in sync with the repo.
+
+---
+
+## Phase 3 — Validate (in COMPOSIO_REMOTE_WORKBENCH)
+
+Run these checks in Python before committing. Fail loudly on any check that fails.
+
+```python
+import re
+
+files_to_check = {
+    "CRITIC.md": [
+        "Full-Stack Critic",
+        "## Modes",
+        "REVIEW", "FIX", "OPTIMIZE", "CLEAN", "VERIFY", "FULL",
+        "1. Correctness",
+        "2. Security",
+        "3. Architecture",
+        "4. API design",
+        "5. Backend",
+        "6. Database",
+        "7. Frontend",
+        "8. Performance",
+        "9. Code quality",
+        "10. Testing",
+        "11. Deployment",
+        "12. Enterprise",
+        "SEVERITY — Title",   # correct heading format
+        "Final Verdict",
+    ],
+    "AGENTS.md": [
+        "zero impact", "running sessions",
+        "REVIEW", "FIX", "FULL",
+        "8 rules",
+    ],
+    "layers/manifest.md": [
+        "transactional", "api-client", "auth", "architecture",
+    ],
+    "layers/transactional-domain.md": [
+        "Idempotency", "Atomicity", "Payment flow",
+        "State machine", "Inventory", "Cancellation",
+    ],
+}
+
+forbidden_terms = ["ItaliaRail", "rail booking", "booking-domain", "[BLOCKER|CRITICAL"]
+
+all_passed = True
+for filename, required_strings in files_to_check.items():
+    content = open(filename).read()
+    for term in required_strings:
+        if term.lower() not in content.lower():
+            print(f"FAIL: '{term}' not found in {filename}")
+            all_passed = False
+    for bad in forbidden_terms:
+        if bad in content:
+            print(f"FAIL: forbidden term '{bad}' found in {filename}")
+            all_passed = False
+
+if all_passed:
+    print("ALL VALIDATION CHECKS PASSED — safe to commit")
+else:
+    print("VALIDATION FAILED — do not commit")
+```
+
+If any check fails: fix the specific file, re-validate, then proceed.
+Do not commit until all checks pass.
+
+---
+
+## Phase 4 — Commit
+
+Single commit to `main` with this exact message:
+
+```
+v2: universal holistic critic — 12 dimensions, 6 modes, fix-capable, all AI runtimes
+
+Changes:
+- CRITIC.md: 12 universal dimensions, 6 modes (REVIEW/FIX/OPTIMIZE/CLEAN/VERIFY/FULL), fixed heading format
+- CLAUDE.md: Claude Code tool discipline, zero-impact attach, memory bootstrap
+- GEMINI.md: Gemini CLI @ reference discipline, zero-impact attach, load priority
+- AGENTS.md: universal entry point, 8 rules, quick start for all AI runtimes
+- agent/fullstack-critic-agent.md: updated workflow, validation step, example requests
+- layers/manifest.md: api-client, auth, architecture, transactional layers added
+- layers/transactional-domain.md: new universal domain layer (payments/orders/inventory)
+- PROJECT_REVIEW.md: universal project context template
+- memory/templates/: all four session memory templates bootstrapped
+- prompts/composio-upgrade-agent.md: self-updating upgrade prompt
+```
+
+---
+
+## Phase 5 — Final report
+
+After commit, output:
+
+```
+UPGRADE COMPLETE
+================
+Commit SHA: <sha>
+Branch: main
+
+Files updated:
+- CRITIC.md         — 12 dimensions, 6 modes, fixed headings
+- CLAUDE.md         — Claude Code discipline + zero-impact attach
+- GEMINI.md         — Gemini CLI discipline + zero-impact attach
+- AGENTS.md         — universal entry point for all AI runtimes
+- agent/fullstack-critic-agent.md — updated Composio contract
+- layers/manifest.md — 4 new layers added
+- layers/transactional-domain.md — NEW
+- PROJECT_REVIEW.md  — NEW
+- memory/templates/PROJECT_PROFILE.md  — NEW or preserved
+- memory/templates/DECISIONS.md        — NEW or preserved
+- memory/templates/REVIEW_HISTORY.md   — NEW or preserved
+- memory/templates/RUN_STATE.md        — NEW or preserved
+- prompts/composio-upgrade-agent.md    — updated
+
+Files skipped (if any):
+- <file> — reason
+
+Validation: ALL CHECKS PASSED
+Ready for public use: YES
+```

package/src/analyzer.js

@@ -0,0 +1,228 @@
+'use strict';
+/**
+ * Analyzer: the engine that produces a finding set + coverage proof for a project.
+ * Guarantees "100% of resources" by walking every non-ignored, non-binary file,
+ * parsing every dependency manifest, and explicitly reporting what (and why) was skipped.
+ */
+const fs = require('fs');
+const path = require('path');
+const { walk, readText, exists } = require('./util');
+const { LINE_RULES } = require('./rules');
+const { analyzeDeps } = require('./deps');
+
+const SEVERITY_RANK = { BLOCKER: 0, CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3, INFO: 4 };
+const CAP_PER_RULE = 12; // cap per (rule,file) to avoid flooding; extra collapsed into a summary finding
+
+const DIMENSIONS = [
+  'Correctness', 'Security', 'Architecture', 'API design', 'Backend', 'Database',
+  'Frontend', 'Performance', 'Code quality', 'Testing', 'Infrastructure', 'Enterprise practices',
+];
+
+function lineOf(text, index) {
+  let line = 1;
+  for (let i = 0; i < index; i++) if (text.charCodeAt(i) === 10) line++;
+  return line;
+}
+
+function snippet(lineText) {
+  const t = lineText.replace(/\s+/g, ' ').trim();
+  return t.length > 160 ? t.slice(0, 157) + '...' : t;
+}
+
+function ruleApplies(rule, ext) {
+  if (!rule.ext) return true;
+  return rule.ext.includes(ext.toLowerCase());
+}
+
+function scanFile(file) {
+  const findings = [];
+  const text = readText(file.abs);
+  if (text == null) return { findings, lines: 0, scannable: false };
+  const lines = text.split(/\r?\n/);
+  // Whole-file suppression: a `critic-ignore-file` marker in the header (for rule-definition files).
+  if (/critic-ignore-file/.test(lines.slice(0, 2).join('\n'))) return { findings, lines: lines.length, scannable: true };
+  const perRule = {};
+
+  for (const rule of LINE_RULES) {
+    if (!ruleApplies(rule, file.ext)) continue;
+    perRule[rule.id] = 0;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (!rule.test.test(line)) continue;
+      if (/critic-ignore/.test(line)) continue; // inline suppression: `// critic-ignore` (like eslint-disable-line)
+      if (rule.skipIf && rule.skipIf(line)) continue;
+      perRule[rule.id]++;
+      if (perRule[rule.id] > CAP_PER_RULE) continue;
+      findings.push({
+        ruleId: rule.id,
+        severity: rule.severity,
+        category: rule.category,
+        dimension: rule.dimension,
+        title: rule.title,
+        file: file.rel,
+        line: i + 1,
+        problem: rule.problem,
+        evidence: snippet(line),
+        impact: rule.impact,
+        fix: rule.fix,
+        verify: rule.verify,
+        confirmed: true,
+      });
+    }
+  }
+  // Collapse overflow into one summary finding per rule.
+  for (const [id, count] of Object.entries(perRule)) {
+    if (count > CAP_PER_RULE) {
+      const rule = LINE_RULES.find((r) => r.id === id);
+      findings.push({
+        ruleId: id + ':overflow', severity: rule.severity, category: rule.category,
+        dimension: rule.dimension, title: `${rule.title} (and ${count - CAP_PER_RULE} more)`,
+        file: file.rel, line: 1, problem: rule.problem, evidence: `${count} matches in this file`,
+        impact: rule.impact, fix: rule.fix, verify: rule.verify, confirmed: true,
+      });
+    }
+  }
+  // Long-file signal.
+  if (lines.length > 500) {
+    findings.push({
+      ruleId: 'long-file', severity: 'LOW', category: 'optimize', dimension: 'Architecture',
+      title: `Large file (${lines.length} lines)`, file: file.rel, line: 1,
+      problem: 'Files this large usually hold more than one responsibility.',
+      evidence: `${lines.length} lines`, impact: 'Harder to test, review, and reason about.',
+      fix: 'Split along responsibility boundaries.', verify: 'each module has one reason to change', confirmed: true,
+    });
+  }
+  return { findings, lines: lines.length, scannable: true };
+}
+
+function structuralFindings(root, files, ctx) {
+  const F = [];
+  const rels = new Set(files.map((f) => f.rel));
+  const hasPkg = rels.has('package.json');
+  const isPython = files.some((f) => f.ext === '.py');
+  const isGo = rels.has('go.mod');
+  const isRust = rels.has('Cargo.toml');
+
+  // Committed .env (real, not the .example) — secrets dimension.
+  for (const f of files) {
+    if (/(^|\/)\.env(\.|$)/.test(f.rel) && !/(example|sample|template|dist|local\.example)/.test(f.rel)) {
+      F.push({
+        ruleId: 'env-committed', severity: 'HIGH', category: 'fix', dimension: 'Security',
+        title: 'Environment file checked into the tree', file: f.rel, line: 1,
+        problem: '.env-style files frequently hold live secrets and are committed by accident.',
+        evidence: f.rel, impact: 'Credential exposure via repository access.',
+        fix: 'Add to .gitignore, remove from history, move config to a secret manager.',
+        verify: 'file no longer tracked; secrets rotated.', confirmed: 'suspected',
+      });
+    }
+  }
+
+  // Test presence (any mainstream language).
+  const testPat = /(^|\/)(tests?|__tests__|spec)\//i;
+  const testFilePat = /(\.test\.|\.spec\.|_test\.(go|py)|test_.*\.py|Tests\.cs|Test[A-Za-z0-9]+\.java)$/i;
+  const hasTests = files.some((f) => testPat.test(f.rel) || testFilePat.test(f.rel));
+  const codeFiles = files.filter((f) => ['.js', '.ts', '.tsx', '.jsx', '.py', '.go', '.rb', '.java', '.rs', '.php', '.cs'].includes(f.ext));
+  if (codeFiles.length >= 5 && !hasTests) {
+    F.push({
+      ruleId: 'no-tests', severity: 'HIGH', category: 'add', dimension: 'Testing',
+      title: 'No test files detected anywhere in the project', file: '.', line: 1,
+      problem: `${codeFiles.length} source files exist but no unit/integration/e2e tests were found.`,
+      evidence: 'no tests/, spec/, *.test.*, *_test.go, test_*.py', impact: 'Every change is shipped unverified; regressions go live.',
+      fix: 'Add a runner and cover the highest-risk paths first (auth, payments, data mutations).',
+      verify: hasPkg ? 'npm test' : (isGo ? 'go test ./...' : (isRust ? 'cargo test' : (isPython ? 'pytest' : 'the suite runs green'))), confirmed: true,
+    });
+  }
+
+  // CI presence.
+  const hasCI = files.some((f) => f.rel.startsWith('.github/workflows/') || /(^|\/)(\.gitlab-ci\.yml|Jenkinsfile|\.circleci\/|azure-pipelines\.yml|\.travis\.yml|bitbucket-pipelines\.yml)$/.test(f.rel));
+  if (!hasCI) {
+    F.push({
+      ruleId: 'no-ci', severity: 'MEDIUM', category: 'add', dimension: 'Infrastructure',
+      title: 'No CI pipeline found', file: '.', line: 1,
+      problem: 'No lint/test/build/security-scan automation gate was detected.',
+      evidence: 'no .github/workflows, .gitlab-ci.yml, Jenkinsfile, etc.', impact: 'Quality depends on manual discipline; bad deploys are not blocked.',
+      fix: 'Add a pipeline that runs lint, type-check, tests, and a dependency audit and blocks on failure.',
+      verify: 'a failing test blocks the pipeline.', confirmed: true,
+    });
+  }
+
+  // Config discipline: any committed env-ish secret filenames.
+  // Documentation / onboarding.
+  const hasReadme = files.some((f) => /(^|\/)README\.(md|rst|txt)$/i.test(f.rel));
+  if (!hasReadme && files.length > 3) {
+    F.push({
+      ruleId: 'no-readme', severity: 'LOW', category: 'add', dimension: 'Enterprise practices',
+      title: 'No README found', file: '.', line: 1, problem: 'No onboarding or run instructions.',
+      evidence: 'README.* absent', impact: 'Slower onboarding; undocumented setup.',
+      fix: 'Add purpose, stack, setup, run, and test instructions.', verify: 'a new contributor can run the app from README alone.', confirmed: true,
+    });
+  }
+  return F;
+}
+
+function summarizeDimensions(all) {
+  const touched = new Set(all.map((f) => f.dimension));
+  return DIMENSIONS.map((d) => ({ dimension: d, touched: touched.has(d) }));
+}
+
+function analyze(root, opts = {}) {
+  const started = Date.now();
+  const { files, skipped } = walk(root);
+  const findings = [];
+  let totalLines = 0;
+  let scanned = 0;
+  const byExt = {};
+
+  if (!opts.skipCode) {
+    for (const f of files) {
+      byExt[f.ext || '(none)'] = (byExt[f.ext || '(none)'] || 0) + 1;
+      const r = scanFile(f);
+      totalLines += r.lines;
+      if (r.scannable) scanned++;
+      findings.push(...r.findings);
+    }
+  }
+
+  // Dependency + package-manifest analysis (100% of ecosystems present).
+  const dep = analyzeDeps(root);
+  findings.push(...dep.findings);
+
+  // Project-wide structural checks.
+  findings.push(...structuralFindings(root, files, { hasPkg: exists(path.join(root, 'package.json')) }));
+
+  findings.sort((a, b) =>
+    (SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity]) ||
+    String(a.file).localeCompare(String(b.file)) || (a.line - b.line));
+
+  const counts = { BLOCKER: 0, CRITICAL: 0, HIGH: 0, MEDIUM: 0, LOW: 0, INFO: 0 };
+  const cats = { fix: 0, optimize: 0, delete: 0, add: 0 };
+  for (const f of findings) { counts[f.severity] = (counts[f.severity] || 0) + 1; cats[f.category] = (cats[f.category] || 0) + 1; }
+
+  return {
+    meta: {
+      root: path.resolve(root),
+      started,
+      durationMs: Date.now() - started,
+      cliVersion: readVersion(),
+    },
+    coverage: {
+      filesScanned: scanned,
+      filesSkipped: skipped.length,
+      totalLines,
+      byExt,
+      skipped: skipped.slice(0, 50),
+      dimensions: summarizeDimensions(findings),
+    },
+    dependencies: dep.ecosystems,
+    counts,
+    categoryCounts: cats,
+    findings,
+  };
+}
+
+function readVersion() {
+  try { return JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')).version; }
+  catch { return '0.0.0'; }
+}
+
+module.exports = { analyze, DIMENSIONS, SEVERITY_RANK };