permission-gap-detector 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -1,9 +1,22 @@
 # Changelog
 
-## 1.0.0 — prepared 19 October 2026 (npm publication pending)
+## 1.0.2
+
+- Reject control characters in route paths before rendering reports.
+- Accept UTF-8 BOM JSON files and literal filenames after `--`.
+- Add command-specific help with documented exit codes.
+- Expand regression coverage to 27 tests and include a clean route example.
+
+
+## 1.0.1
+
+- Keep the distribution focused on source code, usage examples, and package documentation.
+- Simplify the README and published file list.
+
+## 1.0.0
 
 - 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.
+- Add 20 automated tests and usage examples.

package/README.md

@@ -1,6 +1,6 @@
 # Permission Gap Detector
 
-A small, dependency-free CommonJS Node.js package that checks **declared API route permissions**. Built as an Advanced Software Development college assignment.
+A small, dependency-free CommonJS Node.js package that checks **declared API route permissions**.
 
 ## Problem statement
 
@@ -20,13 +20,13 @@ It does not inspect Express middleware or prove that an application is secure.
 
 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:
+Install from npm:
 
 ```bash
 npm install permission-gap-detector
 ```
 
-Until then, install directly from GitHub:
+Alternatively, install directly from GitHub:
 
 ```bash
 npm install github:Aditya030207/npm-package-project
@@ -35,7 +35,7 @@ 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
+npm install /absolute/path/to/permission-gap-detector-1.0.2.tgz
 ```
 
 ## Basic usage
@@ -63,7 +63,7 @@ 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 |
+| `path` | A string starting with `/`, without whitespace or control characters |
 | `access` | Exactly `public`, `authenticated`, or `admin` |
 
 `public` allows anyone; `authenticated` requires a logged-in user; `admin` requires administrator access. These are declarations, not enforcement.
@@ -119,7 +119,7 @@ The three convenience functions return only their named findings. Use `auditRout
 
 ## CLI usage
 
-After npm publication:
+Run directly from npm:
 
 ```bash
 npx permission-gap-detector check routes.json
@@ -132,18 +132,19 @@ 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.
+For a direct shell command, globally install the package with `npm install -g permission-gap-detector` then run `permission-gap check routes.json`. Both binary names point to the same CLI.
 
-From this repository (works before publication):
+From this repository:
 
 ```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 check --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.
+UTF-8 files may begin with a byte order mark (BOM). Files must contain a JSON array, not an object wrapping the array. Paths are relative to the current working directory; quote paths containing spaces. Use `permission-gap check --json -- -routes.json` for a filename beginning with a dash; options must come before `--`. 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
 
@@ -177,6 +178,14 @@ Audit Complete
 
 The example intentionally has issues and exits with code 1.
 
+For a complete set of consistent declarations, run:
+
+```bash
+node bin/cli.js check examples/clean-routes.json
+```
+
+This example uses all three supported permissions, reports 100% declaration coverage with no findings, and exits with code 0. Compare it with `examples/routes.json` to see how missing and conflicting declarations change the result. Neither result verifies middleware enforcement.
+
 ## Development and testing
 
 ```bash
@@ -188,7 +197,7 @@ 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.
+The 27 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
 
@@ -204,41 +213,16 @@ npm-package-project/
 ├── tests/package.test.js    # API and CLI tests
 ├── examples/
 │   ├── basic.js
-│   └── routes.json
+│   ├── routes.json
+│   └── clean-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.

package/bin/cli.js

@@ -4,24 +4,30 @@ 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';
+// Arguments after -- are literal filenames, even when they begin with a dash.
+const separator = args.indexOf('--');
+const options = separator === -1 ? args : args.slice(0, separator);
+const filenames = separator === -1 ? [] : args.slice(separator + 1);
+const json = options.includes('--json');
+const usage = 'Usage: permission-gap check <routes.json> [--json]\n       permission-gap check [--json] -- <filename>\nOptions: --help, --version, --json\nExit codes: 0 = no findings, 1 = audit findings, 2 = input error';
 
 try {
-  if (args.length === 1 && args[0] === '--help') {
+  if ((args.length === 1 && args[0] === '--help') ||
+      (args.length === 2 && args[0] === 'check' && args[1] === '--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) {
+    const positional = [...options.filter(arg => arg !== '--json'), ...filenames];
+    const unknownOption = options.some(arg => arg.startsWith('-') && arg !== '--json');
+    if (positional.length !== 2 || positional[0] !== 'check' || unknownOption || options.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); }
+    try { routes = JSON.parse(content.replace(/^\uFEFF/, '')); }
     catch { throw new Error(`Invalid JSON in file: ${positional[1]}`); }
     const result = auditRoutes(routes);
     console.log(json ? JSON.stringify(result, null, 2) : generateReport(result));

package/examples/clean-routes.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "permission-gap-detector",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Check declared API route permissions for missing policies, duplicates, and conflicts.",
   "main": "src/index.js",
   "type": "commonjs",
@@ -12,9 +12,7 @@
     "src/",
     "bin/",
     "examples/",
-    "CHANGELOG.md",
-    "VIVA_GUIDE.md",
-    "PROJECT_PROGRESS.md"
+    "CHANGELOG.md"
   ],
   "scripts": {
     "test": "node --test",

package/src/checkPermissions.js

@@ -9,8 +9,8 @@ function validateRoutes(routes) {
     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.' });
+        typeof route.path !== 'string' || !route.path.startsWith('/') || /[\s\x00-\x1f\x7f-\x9f]/.test(route.path)) {
+      invalidRoutes.push({ index, message: 'Expected an object with a supported HTTP method and a path starting with / without whitespace or control characters.' });
       continue;
     }
     validRoutes.push({ index, method: route.method.toUpperCase(), path: route.path, access: route.access });

package/PROJECT_PROGRESS.md

@@ -1,21 +0,0 @@
-# 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/VIVA_GUIDE.md

@@ -1,52 +0,0 @@
-# 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.