permission-gap-detector 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 1.0.0 — prepared 19 October 2026 (npm publication pending)
+
+- Add missing and invalid permission checks.
+- Add duplicate and conflicting policy detection.
+- Add summary counts and declaration coverage.
+- Add CommonJS API and CLI with JSON output and exit codes.
+- Add 20 tests, examples, and college evaluation documentation.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aditya030207
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROJECT_PROGRESS.md

@@ -0,0 +1,21 @@
+# Project progress
+
+## Intended schedule: 4–26 October 2026
+
+These are planned milestones, not claims that work occurred on those dates.
+
+| Planned dates | Milestones |
+| --- | --- |
+| October 4–6: Planning | Choose package idea; define problem statement; plan features. |
+| October 7–10: Basic Setup | Initialize Node.js project; design route format; create package structure. |
+| October 11–14: Core Development | Missing permission detection; permission validation; duplicate detection. |
+| October 15–18: Remaining Features | Permission conflicts; coverage calculation; report output. |
+| October 19–21: Testing | CLI; unit tests; input validation; bug fixes. |
+| October 22–24: Documentation | README; usage examples; installation instructions; final testing. |
+| October 25–26: Publication and Submission | NPM packaging; public GitHub repository; NPM publication; final demonstration. |
+
+## Actual work
+
+19 October 2026: Implemented the API and CLI, wrote and passed 20 automated tests, added examples, README, MIT license, changelog, and viva guide. Git commits use their real creation timestamps. Implementation was completed earlier than some planned milestones.
+
+npm publication remains pending npm authentication. Publication and submission must not be presented as completed until separately verified.

package/README.md

@@ -1,3 +1,252 @@
-# Temporary Holding Version
+# Permission Gap Detector
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A small, dependency-free CommonJS Node.js package that checks **declared API route permissions**. Built as an Advanced Software Development college assignment.
+
+## Problem statement
+
+While building an Express REST API, a developer can forget to specify who should access a route. A route list makes these decisions visible. This package finds missing or inconsistent declarations so they can be reviewed.
+
+It does not inspect Express middleware or prove that an application is secure.
+
+## Features
+
+- Detect missing permissions and unsupported permission values.
+- Support `public`, `authenticated`, and `admin` policies.
+- Detect repeated method/path pairs and conflicting valid policies.
+- Return structured findings and permission declaration coverage.
+- Read route lists from JSON using a simple CLI.
+
+## Installation
+
+Requires Node.js 20 or newer and npm. No external dependencies.
+
+The release is prepared as version 1.0.0. **npm publication is pending account authentication.** Once published:
+
+```bash
+npm install permission-gap-detector
+```
+
+Until then, install directly from GitHub:
+
+```bash
+npm install github:Aditya030207/npm-package-project
+```
+
+Or run `npm pack` in this repository and install the resulting archive in another project:
+
+```bash
+npm install /absolute/path/to/permission-gap-detector-1.0.0.tgz
+```
+
+## Basic usage
+
+```js
+const { auditRoutes } = require('permission-gap-detector');
+
+const routes = [
+  { method: 'GET', path: '/products', access: 'public' },
+  { method: 'DELETE', path: '/products/:id' }
+];
+
+const result = auditRoutes(routes);
+console.log(result.summary);
+console.log(result.findings.missingPermissions);
+// [{ index: 1, method: 'DELETE', path: '/products/:id' }]
+```
+
+Maintain this route list alongside your Express routes. The package does not automatically discover routes.
+
+## Route format and validation
+
+Input is an array of ordinary route objects. Each object needs:
+
+| Field | Accepted values |
+| --- | --- |
+| `method` | GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, CONNECT, TRACE; case-insensitive |
+| `path` | A string starting with `/`, without whitespace |
+| `access` | Exactly `public`, `authenticated`, or `admin` |
+
+`public` allows anyone; `authenticated` requires a logged-in user; `admin` requires administrator access. These are declarations, not enforcement.
+
+Absent, undefined, null, empty, and whitespace-only access values are missing. Other unsupported values are invalid permissions. Invalid route objects, methods, and paths are reported as invalid routes and excluded from other checks. Additional fields are ignored. Methods are normalized to uppercase without changing the input. Paths are compared exactly: `/users`, `/Users`, `/users/`, and parameter names are distinct.
+
+## API
+
+All four functions accept a route array and leave it unchanged. A non-array argument throws `TypeError`. Invalid entries inside an array are reported by `auditRoutes` instead of throwing.
+
+### `auditRoutes(routes)`
+
+Returns `{ summary, findings, hasIssues }`.
+
+`summary` contains:
+
+| Field | Meaning |
+| --- | --- |
+| `totalRoutes` | All submitted definitions, including invalid entries |
+| `validPermissions` | Structurally valid definitions with a supported access value |
+| `missingPermissions` | Valid route structures with missing access |
+| `invalidPermissions` | Valid route structures with unsupported access |
+| `invalidRoutes` | Invalid route structures |
+| `duplicateRoutes` | Extra definitions beyond the first in each repeated method/path group |
+| `conflictingRoutes` | Method/path groups with at least two distinct supported policies |
+| `coveragePercentage` | Valid permissions divided by total definitions, multiplied by 100, rounded to one decimal |
+
+The four permission/validation categories sum to `totalRoutes`. An empty array has 0% coverage because no declarations were checked. Duplicates and conflicts overlap with these categories and must not be added to them. Three copies of one route count as two duplicates. A conflicting group counts once. Valid policies on duplicates still count toward declaration coverage: **100% coverage can coexist with conflicts and does not mean secure**.
+
+`findings` contains five arrays:
+
+- `missingPermissions`: `{ index, method, path }`.
+- `invalidPermissions`: `{ index, method, path, access }`.
+- `invalidRoutes`: `{ index, message }`.
+- `duplicateRoutes`: `{ method, path, indices, extraDefinitions }`.
+- `conflictingPermissions`: `{ method, path, indices, permissions }`.
+
+Indices are zero-based positions in the original array. Conflict indices include all definitions in that group; `permissions` lists its distinct supported values. Missing and invalid policies do not themselves create conflicts. `hasIssues` is true when any findings array is nonempty.
+
+### `findMissingPermissions(routes)`
+
+Returns the `missingPermissions` findings array.
+
+### `findDuplicateRoutes(routes)`
+
+Returns the `duplicateRoutes` findings array, one object per repeated group.
+
+### `findConflictingPermissions(routes)`
+
+Returns the `conflictingPermissions` findings array, one object per conflicting group.
+
+The three convenience functions return only their named findings. Use `auditRoutes` to see validation errors as well.
+
+## CLI usage
+
+After npm publication:
+
+```bash
+npx permission-gap-detector check routes.json
+```
+
+After installation into a project:
+
+```bash
+npx --no-install permission-gap check routes.json
+npx --no-install permission-gap check routes.json --json
+```
+
+For a direct shell command, globally install the package with `npm install -g permission-gap-detector` after publication, then run `permission-gap check routes.json`. Both binary names point to the same CLI.
+
+From this repository (works before publication):
+
+```bash
+node bin/cli.js check examples/routes.json
+node bin/cli.js check examples/routes.json --json
+node bin/cli.js --help
+node bin/cli.js --version
+```
+
+Files must contain a JSON array, not an object wrapping the array. Paths are relative to the current working directory; quote paths containing spaces. Exit codes: **0** = no findings, **1** = audit findings, **2** = invalid command, unreadable file, malformed JSON, or non-array input. Human-readable failures go to stderr. With `--json`, failures are `{ "error": "message" }` on stdout.
+
+## Example output
+
+Running the included six-definition example produces:
+
+```text
+==================================
+     PERMISSION GAP DETECTOR
+==================================
+
+Total Routes Checked: 6
+Valid Permissions: 5
+Missing Permissions: 1
+Invalid Permissions: 0
+Invalid Route Definitions: 0
+Duplicate Routes (extra definitions): 2
+Conflicting Policies (route groups): 1
+
+Permission Coverage: 83.3%
+
+Issues Found:
+[WARNING] DELETE /products/:id: Missing permission declaration (index 2).
+[WARNING] GET /products: Duplicate route definition (indices 0, 3).
+[WARNING] GET /admin: Duplicate route definition (indices 4, 5).
+[ERROR] GET /admin: Conflicting permissions: admin, public.
+
+==================================
+Audit Complete
+==================================
+```
+
+The example intentionally has issues and exits with code 1.
+
+## Development and testing
+
+```bash
+git clone https://github.com/Aditya030207/npm-package-project.git
+cd npm-package-project
+npm ci
+npm test
+node examples/basic.js
+npm pack --dry-run
+```
+
+The 20 automated tests use `node:test` and strict assertions. They cover valid policies, input validation, missing permissions, duplicates, conflicts, counting, immutability, reports, and CLI behavior with real temporary files and child processes.
+
+## Source structure
+
+```text
+npm-package-project/
+├── src/
+│   ├── index.js             # Four public exports
+│   ├── auditRoutes.js       # Combine checks and calculate summary
+│   ├── checkPermissions.js  # Validate input and access policies
+│   ├── checkDuplicates.js   # Group routes and find conflicts
+│   └── generateReport.js    # Format readable terminal output
+├── bin/cli.js               # Arguments, JSON file reading, exit codes
+├── tests/package.test.js    # API and CLI tests
+├── examples/
+│   ├── basic.js
+│   └── routes.json
+├── package.json
+├── package-lock.json
+├── README.md
+├── CHANGELOG.md
+├── PROJECT_PROGRESS.md
+├── VIVA_GUIDE.md
+├── LICENSE
+└── .gitignore
+```
+
+## Publication
+
+From the package directory, authenticate interactively and publish:
+
+```bash
+npm login
+npm whoami
+npm test
+npm pack --dry-run
+npm publish --access public
+npm view permission-gap-detector@1.0.0 version
+```
+
+Complete any npm browser or two-factor authentication prompts. The name was absent from the npm registry on 19 October 2026; availability is not a reservation. If npm rejects the name, select an available name or your own npm scope and update the package metadata and usage instructions. After successful publication, update this README's pending status. Verify installation in a fresh directory with `npm install permission-gap-detector@1.0.0`, then run the basic usage example and CLI.
+
+## College demonstration
+
+1. Explain the missing-permission problem and the distinction between declarations and enforcement.
+2. Run `npm test` to show the test results.
+3. Run `node bin/cli.js check examples/routes.json` and explain the missing policy, two extra duplicates, one conflicting group, and 83.3% coverage.
+4. In a copy of the JSON, assign `admin` to the DELETE route and remove the repeated GET definitions. Rerun to show no issues and 100% coverage.
+5. Show the exported functions in `src/index.js` and the grouping loop in `src/checkDuplicates.js`.
+6. Show the GitHub repository and install the packed archive into a separate project. Show the npm listing once publication is complete.
+
+## Limitations
+
+This audits only supplied route declarations. It does not scan source code, discover Express routes, execute middleware, validate tokens, enforce access rules, or assess application security. It does not infer route equivalence, inherited policies, Express mount paths, or wildcard matching. A public policy on a sensitive route is only detected as a conflict if another definition declares a different valid policy. Keep route declarations synchronized with the actual application.
+
+## Contributing
+
+Open an issue describing a problem or propose a small change. Add a meaningful test for changed behavior and run `npm test`. Keep the project simple and dependency-free.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/VIVA_GUIDE.md

@@ -0,0 +1,52 @@
+# Viva guide
+
+**What problem does this package solve?**
+It finds missing or inconsistent access declarations in a developer-maintained API route list.
+
+**Why did we create it?**
+It is easy to add an endpoint and forget to record who should access it. This reusable check makes omissions visible before review or release.
+
+**How does auditRoutes() work?**
+It checks that the input is an array, separates invalid route structures, checks access values, groups matching routes, and returns findings with counts and coverage. It does not change the input.
+
+**How are duplicates detected?**
+A Map groups definitions using the uppercase HTTP method plus the exact path. A group with more than one definition is duplicated. A group of three contributes two extra definitions to the duplicate count.
+
+**How are permission conflicts detected?**
+Within each duplicate group, a Set collects distinct supported permissions. More than one supported permission means a conflict. Invalid or missing values have separate findings.
+
+**How is coverage calculated?**
+Valid permission definitions / total submitted definitions × 100, rounded to one decimal. Empty input has 0%. Duplicate definitions stay in the denominator and may have valid policies. Coverage describes declaration completeness; even 100% can contain conflicts.
+
+**Authentication versus authorization?**
+Authentication checks who a person is, such as verifying their login. Authorization checks what that person may do, such as deleting a user. This package labels intended access but implements neither mechanism.
+
+**What is package.json?**
+It describes the npm package: name, version, main module, CLI commands, scripts, license, Node requirement, and repository. The files field controls which project files go into the published archive.
+
+**What does module.exports do?**
+It makes functions available to other files through CommonJS require(). Our entry point exports four named functions.
+
+**How do automated tests work?**
+Node's built-in runner executes test cases. Assertions compare actual behavior with expected results. CLI tests launch a real child process and use temporary files. npm test runs node --test. A failing assertion makes the test command fail.
+
+**Why no dependencies?**
+The checks need only loops, arrays, Map, and Set. Node already provides file reading, process arguments, and a test runner.
+
+**How is an npm package published?**
+Choose an available name, prepare metadata and files, run tests and npm pack --dry-run, log in with npm login, then run npm publish --access public. Complete required authentication prompts and verify the registry version and a fresh install. This project's publication is pending login; do not claim it is already published.
+
+**What is version 1.0.0?**
+It is the first working release. Semantic versioning uses major.minor.patch: breaking API changes increase major, compatible features increase minor, and compatible fixes increase patch.
+
+**What do CLI exit codes mean?**
+Zero means the audit found no issues; one means findings were detected; two means an input or command error. Other scripts can use these statuses.
+
+**What are the limitations?**
+The package sees only supplied declarations. It does not discover routes or verify middleware, authentication, authorization, or overall security. Paths are compared exactly; it does not understand Express routing semantics.
+
+**How would you demonstrate reuse?**
+Install the archive in an empty project, require permission-gap-detector, call auditRoutes with a route array, and show the summary. Then run the installed CLI on the same route data.
+
+**What is the approximate algorithmic cost?**
+Validation and permission checks visit each entry once. Grouping uses a Map; checking policies visits each group entry once. Typical time and memory are linear in the number of definitions, with string handling also depending on path length.

package/bin/cli.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+const fs = require('node:fs');
+const { auditRoutes } = require('../src');
+const generateReport = require('../src/generateReport');
+const { version } = require('../package.json');
+const args = process.argv.slice(2);
+const json = args.includes('--json');
+const usage = 'Usage: permission-gap check <routes.json> [--json]\nOptions: --help, --version, --json';
+
+try {
+  if (args.length === 1 && args[0] === '--help') {
+    console.log(usage);
+  } else if (args.length === 1 && args[0] === '--version') {
+    console.log(version);
+  } else {
+    const positional = args.filter(arg => arg !== '--json');
+    if (positional.length !== 2 || positional[0] !== 'check' || positional[1].startsWith('--') || args.filter(arg => arg === '--json').length > 1) {
+      throw new Error(usage);
+    }
+    let content;
+    try { content = fs.readFileSync(positional[1], 'utf8'); }
+    catch { throw new Error(`Cannot read file: ${positional[1]}`); }
+    let routes;
+    try { routes = JSON.parse(content); }
+    catch { throw new Error(`Invalid JSON in file: ${positional[1]}`); }
+    const result = auditRoutes(routes);
+    console.log(json ? JSON.stringify(result, null, 2) : generateReport(result));
+    process.exitCode = result.hasIssues ? 1 : 0;
+  }
+} catch (error) {
+  if (json) console.log(JSON.stringify({ error: error.message }));
+  else console.error(`Error: ${error.message}`);
+  process.exitCode = 2;
+}

package/examples/basic.js

@@ -0,0 +1,3 @@
+const { auditRoutes } = require('../src');
+const routes = require('./routes.json');
+console.log(JSON.stringify(auditRoutes(routes), null, 2));

package/examples/routes.json

@@ -0,0 +1,31 @@
+[
+  {
+    "method": "GET",
+    "path": "/products",
+    "access": "public"
+  },
+  {
+    "method": "POST",
+    "path": "/products",
+    "access": "authenticated"
+  },
+  {
+    "method": "DELETE",
+    "path": "/products/:id"
+  },
+  {
+    "method": "GET",
+    "path": "/products",
+    "access": "public"
+  },
+  {
+    "method": "GET",
+    "path": "/admin",
+    "access": "admin"
+  },
+  {
+    "method": "GET",
+    "path": "/admin",
+    "access": "public"
+  }
+]

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "permission-gap-detector",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Check declared API route permissions for missing policies, duplicates, and conflicts.",
+  "main": "src/index.js",
+  "type": "commonjs",
+  "bin": {
+    "permission-gap": "bin/cli.js",
+    "permission-gap-detector": "bin/cli.js"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "examples/",
+    "CHANGELOG.md",
+    "VIVA_GUIDE.md",
+    "PROJECT_PROGRESS.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "permissions",
+    "routes",
+    "express",
+    "audit",
+    "cli"
+  ],
+  "author": "Aditya030207",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Aditya030207/npm-package-project.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Aditya030207/npm-package-project/issues"
+  },
+  "homepage": "https://github.com/Aditya030207/npm-package-project#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/auditRoutes.js

@@ -0,0 +1,25 @@
+const { validateRoutes, checkPermissions } = require('./checkPermissions');
+const checkDuplicates = require('./checkDuplicates');
+
+function auditRoutes(routes) {
+  const { validRoutes, invalidRoutes } = validateRoutes(routes);
+  const { validPermissions, missingPermissions, invalidPermissions } = checkPermissions(validRoutes);
+  const { duplicateRoutes, conflictingPermissions } = checkDuplicates(validRoutes);
+  const findings = { missingPermissions, invalidPermissions, invalidRoutes, duplicateRoutes, conflictingPermissions };
+  return {
+    summary: {
+      totalRoutes: routes.length,
+      validPermissions,
+      missingPermissions: missingPermissions.length,
+      invalidPermissions: invalidPermissions.length,
+      invalidRoutes: invalidRoutes.length,
+      duplicateRoutes: duplicateRoutes.reduce((sum, group) => sum + group.extraDefinitions, 0),
+      conflictingRoutes: conflictingPermissions.length,
+      coveragePercentage: routes.length === 0 ? 0 : Math.round(validPermissions / routes.length * 1000) / 10
+    },
+    findings,
+    hasIssues: Object.values(findings).some(items => items.length > 0)
+  };
+}
+
+module.exports = auditRoutes;

package/src/checkDuplicates.js

@@ -0,0 +1,26 @@
+const { ACCESS_TYPES } = require('./checkPermissions');
+
+function checkDuplicates(routes) {
+  const groups = new Map();
+  for (const route of routes) {
+    const key = `${route.method} ${route.path}`;
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(route);
+  }
+  const duplicateRoutes = [];
+  const conflictingPermissions = [];
+  for (const group of groups.values()) {
+    if (group.length < 2) continue;
+    const { method, path } = group[0];
+    const indices = group.map(route => route.index);
+    duplicateRoutes.push({ method, path, indices, extraDefinitions: group.length - 1 });
+    // Only supported policies can conflict; other values have their own findings.
+    const permissions = [...new Set(group.map(route => route.access).filter(access => ACCESS_TYPES.includes(access)))];
+    if (permissions.length > 1) {
+      conflictingPermissions.push({ method, path, indices, permissions });
+    }
+  }
+  return { duplicateRoutes, conflictingPermissions };
+}
+
+module.exports = checkDuplicates;

package/src/checkPermissions.js

@@ -0,0 +1,38 @@
+const ACCESS_TYPES = ['public', 'authenticated', 'admin'];
+const METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS', 'CONNECT', 'TRACE'];
+
+function validateRoutes(routes) {
+  if (!Array.isArray(routes)) throw new TypeError('Routes must be an array.');
+  const validRoutes = [];
+  const invalidRoutes = [];
+  for (let index = 0; index < routes.length; index++) {
+    const route = routes[index];
+    if (!route || typeof route !== 'object' || Array.isArray(route) ||
+        typeof route.method !== 'string' || !METHODS.includes(route.method.toUpperCase()) ||
+        typeof route.path !== 'string' || !route.path.startsWith('/') || /\s/.test(route.path)) {
+      invalidRoutes.push({ index, message: 'Expected an object with a supported HTTP method and a path starting with / without whitespace.' });
+      continue;
+    }
+    validRoutes.push({ index, method: route.method.toUpperCase(), path: route.path, access: route.access });
+  }
+  return { validRoutes, invalidRoutes };
+}
+
+function checkPermissions(routes) {
+  const missingPermissions = [];
+  const invalidPermissions = [];
+  let validPermissions = 0;
+  for (const route of routes) {
+    const { index, method, path, access } = route;
+    if (access === undefined || access === null || (typeof access === 'string' && access.trim() === '')) {
+      missingPermissions.push({ index, method, path });
+    } else if (!ACCESS_TYPES.includes(access)) {
+      invalidPermissions.push({ index, method, path, access });
+    } else {
+      validPermissions++;
+    }
+  }
+  return { validPermissions, missingPermissions, invalidPermissions };
+}
+
+module.exports = { validateRoutes, checkPermissions, ACCESS_TYPES };

package/src/generateReport.js

@@ -0,0 +1,21 @@
+function generateReport(result) {
+  const { summary: s, findings: f } = result;
+  const lines = [
+    '==================================', '     PERMISSION GAP DETECTOR', '==================================', '',
+    `Total Routes Checked: ${s.totalRoutes}`, `Valid Permissions: ${s.validPermissions}`,
+    `Missing Permissions: ${s.missingPermissions}`, `Invalid Permissions: ${s.invalidPermissions}`,
+    `Invalid Route Definitions: ${s.invalidRoutes}`, `Duplicate Routes (extra definitions): ${s.duplicateRoutes}`,
+    `Conflicting Policies (route groups): ${s.conflictingRoutes}`, '',
+    `Permission Coverage: ${s.coveragePercentage}%`, '', 'Issues Found:'
+  ];
+  for (const route of f.missingPermissions) lines.push(`[WARNING] ${route.method} ${route.path}: Missing permission declaration (index ${route.index}).`);
+  for (const route of f.invalidPermissions) lines.push(`[ERROR] ${route.method} ${route.path}: Invalid permission; use public, authenticated, or admin (index ${route.index}).`);
+  for (const route of f.invalidRoutes) lines.push(`[ERROR] Index ${route.index}: ${route.message}`);
+  for (const route of f.duplicateRoutes) lines.push(`[WARNING] ${route.method} ${route.path}: Duplicate route definition (indices ${route.indices.join(', ')}).`);
+  for (const route of f.conflictingPermissions) lines.push(`[ERROR] ${route.method} ${route.path}: Conflicting permissions: ${route.permissions.join(', ')}.`);
+  if (!result.hasIssues) lines.push('No issues found.');
+  lines.push('', '==================================', 'Audit Complete', '==================================');
+  return lines.join('\n');
+}
+
+module.exports = generateReport;

package/src/index.js

@@ -0,0 +1,15 @@
+const auditRoutes = require('./auditRoutes');
+
+function findMissingPermissions(routes) {
+  return auditRoutes(routes).findings.missingPermissions;
+}
+
+function findDuplicateRoutes(routes) {
+  return auditRoutes(routes).findings.duplicateRoutes;
+}
+
+function findConflictingPermissions(routes) {
+  return auditRoutes(routes).findings.conflictingPermissions;
+}
+
+module.exports = { auditRoutes, findMissingPermissions, findDuplicateRoutes, findConflictingPermissions };