trimcode 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 trimcode contributors
+
+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/README.md

@@ -1,3 +1,128 @@
-# Temporary Holding Version
+# trimcode
 
-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.
+Turn a Node.js source file into a simple, structured JSON summary: what it imports, what it exports, which functions and classes it defines, which HTTP routes it declares, what it does when it loads, and which environment variables it reads.
+
+It parses the file into an AST and reads it. It never runs your code, never touches the network, and has a single dependency ([acorn](https://github.com/acornjs/acorn)). It works on CommonJS and ES modules, and does not need JSDoc comments.
+
+## Install
+
+```sh
+npm install trimcode          # as a library
+npx trimcode src/server.js    # or just run it
+```
+
+Requires Node.js 18.3 or newer.
+
+## Command line
+
+```sh
+trimcode <file...> [options]
+cat file.js | trimcode
+
+  -o, --out <path>          write the JSON to a file instead of stdout
+  -c, --compact             print JSON on a single line
+      --source-type <type>  auto (default), module or script
+  -h, --help
+  -v, --version
+```
+
+One file prints one JSON object; several files print an array. A file that cannot be read or parsed is reported on stderr as `file:line:column: message`, the other files are still printed, and the exit code is `1`.
+
+## API
+
+```js
+import { analyze, analyzeFile } from 'trimcode';
+
+const result = analyze(sourceCode, { filename: 'server.js' });
+const same = await analyzeFile('server.js');
+```
+
+`analyze` throws a `ParseError` (with 1-based `line` and `column`) if the source is not valid JavaScript. TypeScript definitions are included.
+
+## Example
+
+Given [`examples/server.js`](examples/server.js), a small Express app, `trimcode examples/server.js` prints (trimmed here):
+
+```json
+{
+  "file": "examples/server.js",
+  "moduleType": "commonjs",
+  "summary": "CommonJS module, 41 lines. Depends on 2 npm packages, 1 Node built-in and 1 local module. Defines 4 functions. Exports 1 name. Declares 2 HTTP routes. When loaded it loads environment variables from a file, touches the filesystem and starts a server. Reads 2 environment variables.",
+  "dependencies": { "builtin": ["fs"], "packages": ["express", "dotenv"], "local": ["./db"] },
+  "exports": [{ "name": "getUser", "kind": "function", "style": "commonjs", "line": 41 }],
+  "functions": [
+    {
+      "name": "getUser",
+      "kind": "function",
+      "async": true,
+      "params": ["id"],
+      "exported": true,
+      "doc": "Looks a user up and strips private fields.",
+      "complexity": 2,
+      "calls": ["findUser", "publicView"],
+      "localCalls": ["publicView"]
+    },
+    {
+      "name": "GET /users/:id",
+      "kind": "route-handler",
+      "calls": ["res.json", "getUser"],
+      "localCalls": ["getUser"]
+    }
+  ],
+  "routes": [
+    { "method": "GET", "path": "/users/:id", "handler": "GET /users/:id", "middleware": ["requireAuth"], "line": 28 },
+    { "method": "POST", "path": "/users", "handler": "POST /users", "line": 32 }
+  ],
+  "sideEffects": [
+    { "type": "env-load", "detail": "dotenv.config", "line": 4 },
+    { "type": "filesystem", "detail": "fs.mkdirSync", "line": 37 },
+    { "type": "server-listen", "detail": "PORT", "line": 39 }
+  ],
+  "env": [
+    { "name": "PORT", "line": 7, "hasDefault": true },
+    { "name": "LOG_DIR", "line": 8, "hasDefault": false }
+  ]
+}
+```
+
+## Output reference
+
+| Field | What it holds |
+| --- | --- |
+| `schemaVersion` | Version of the output shape. It only changes on breaking changes. |
+| `file`, `moduleType` | The filename you gave, and `esm` or `commonjs`. |
+| `summary` | One short paragraph in plain language, built from the fields below. |
+| `stats` | Line, import, export, function, class and route counts. |
+| `dependencies` | Unique `builtin`, `packages` and `local` modules. |
+| `imports` | `import`, `require()` and `import()`: source, kind, binding, named imports, line. |
+| `exports` | Named and default exports for both module systems, including re-exports. |
+| `functions` | Named functions, arrows, methods and route handlers, with params, async/generator flags, JSDoc summary, complexity, nesting, `calls` and `localCalls`. |
+| `classes` | Name, `extends`, methods (static, getters, async). |
+| `routes` | Express/Fastify-style routes: method, path, handler, middleware. |
+| `sideEffects` | What happens when the file loads (see below). |
+| `env` | `process.env` variables read, and whether a fallback is supplied. |
+
+Side-effect types: `server-listen`, `server-create`, `connection`, `env-load`, `process-handler`, `process-exit`, `timer`, `filesystem`, `child-process`, `console-output`, `global-mutation`, `top-level-await`.
+
+## What to know before relying on it
+
+This is static analysis, so some answers are best-effort:
+
+- **Routes are heuristic.** A call like `x.get('/path', handler)` counts when `x` looks like a router (`app`, `router`, `fastify`, `userRouter`, ...) or a handler is an inline function. Known HTTP clients (`axios`, `got`, `supertest`, ...) are excluded. A router with an unusual name and named handlers can be missed.
+- **Side effects are load-time only.** Code at the top level and inside an immediately-invoked function is reported. Code inside a function that is called later is not, so `main()` hiding a `listen()` will not show up.
+- **The call graph is by name.** `localCalls` links calls to functions defined in the same file by name (and `this.method()` inside a class). It does not follow calls across files or through variables.
+- **Complexity is approximate.** It counts branches (`if`, loops, `case`, `catch`, `?:`, `&&`, `||`, `??`) and attributes anonymous callbacks to the named function that contains them.
+- **Export kinds for imported names are generic.** `export { Foo }` where `Foo` was imported from another file is reported as `value`.
+- **Plain JavaScript only.** TypeScript, JSX and Flow syntax are reported as parse errors.
+- **Dynamic imports** whose specifier is not a string literal are listed with `"kind": "dynamic"` and `"source": null`.
+
+## Development
+
+```sh
+npm install
+npm test        # node:test, no extra dependencies
+```
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+import { analyze, ParseError } from '../src/index.js';
+
+const USAGE = `trimcode - summarize a Node.js source file as structured JSON
+
+Usage:
+  trimcode <file...> [options]
+  cat file.js | trimcode [options]
+
+Options:
+  -o, --out <path>          Write the JSON to a file instead of stdout
+  -c, --compact             Print JSON on a single line
+      --source-type <type>  auto (default), module or script
+  -h, --help                Show this help
+  -v, --version             Show the version
+
+One file prints one JSON object; several files print an array.
+Files that cannot be read or parsed are reported on stderr and the exit code is 1.
+`;
+
+function fail(message, code = 2) {
+  process.stderr.write(`trimcode: ${message}\n`);
+  process.exit(code);
+}
+
+let args;
+try {
+  args = parseArgs({
+    allowPositionals: true,
+    options: {
+      out: { type: 'string', short: 'o' },
+      compact: { type: 'boolean', short: 'c' },
+      'source-type': { type: 'string' },
+      help: { type: 'boolean', short: 'h' },
+      version: { type: 'boolean', short: 'v' },
+    },
+  });
+} catch (err) {
+  fail(`${err.message}\n\n${USAGE}`);
+}
+
+const { values, positionals } = args;
+
+if (values.help) {
+  process.stdout.write(USAGE);
+  process.exit(0);
+}
+if (values.version) {
+  const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+  process.stdout.write(`${pkg.version}\n`);
+  process.exit(0);
+}
+
+const sourceType = values['source-type'] ?? 'auto';
+if (!['auto', 'module', 'script'].includes(sourceType)) {
+  fail(`--source-type must be "auto", "module" or "script" (got "${sourceType}")`);
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+const inputs = positionals.length ? positionals : [];
+if (inputs.length === 0) {
+  if (process.stdin.isTTY) {
+    process.stderr.write(USAGE);
+    process.exit(2);
+  }
+  inputs.push('-');
+}
+
+const results = [];
+let failed = false;
+
+for (const input of inputs) {
+  try {
+    const code = input === '-' ? await readStdin() : await readFile(input, 'utf8');
+    results.push(analyze(code, { filename: input === '-' ? null : input, sourceType }));
+  } catch (err) {
+    failed = true;
+    const name = input === '-' ? '<stdin>' : input;
+    if (err instanceof ParseError) {
+      const where = err.line ? `:${err.line}${err.column ? `:${err.column}` : ''}` : '';
+      process.stderr.write(`${name}${where}: ${err.message}\n`);
+    } else {
+      process.stderr.write(`${name}: ${err.message}\n`);
+    }
+  }
+}
+
+if (results.length > 0) {
+  const output = inputs.length === 1 ? results[0] : results;
+  const json = `${JSON.stringify(output, null, values.compact ? 0 : 2)}\n`;
+  if (values.out) await writeFile(values.out, json);
+  else process.stdout.write(json);
+}
+
+process.exitCode = failed ? 1 : 0;

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "trimcode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Turn a Node.js source file into a simple, structured JSON summary: imports, exports, functions, classes, HTTP routes, side effects and env vars.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "trimcode": "bin/cli.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=18.3"
+  },
+  "dependencies": {
+    "acorn": "^8.18.0"
+  },
+  "keywords": [
+    "ast",
+    "static-analysis",
+    "code-summary",
+    "code-structure",
+    "javascript",
+    "nodejs",
+    "json",
+    "cli",
+    "express",
+    "documentation"
+  ],
+  "license": "MIT"
+}

package/src/index.d.ts

@@ -0,0 +1,141 @@
+export declare const SCHEMA_VERSION: 1;
+
+export interface AnalyzeOptions {
+  /** Stored in the result as `file`. */
+  filename?: string;
+  /** `auto` tries an ES module first, then a sloppy-mode script. Default: `auto`. */
+  sourceType?: 'auto' | 'module' | 'script';
+}
+
+export interface ImportEntry {
+  /** The specifier as written, or `null` when it is computed at runtime. */
+  source: string | null;
+  kind: 'builtin' | 'package' | 'local' | 'dynamic';
+  /** npm package name (`@scope/name` or `name`) when `kind` is `package`. */
+  package?: string;
+  style: 'import' | 'require' | 'dynamic-import';
+  /** Local name bound to the whole module (default or namespace import, `const x = require()`). */
+  binding?: string;
+  /** Named imports / destructured names, as exported by the module. */
+  names?: string[];
+  line: number;
+}
+
+export interface ExportEntry {
+  name: string;
+  kind: 'function' | 'class' | 'value' | 're-export';
+  style: 'commonjs' | 'esm';
+  /** Module re-exported from, for `export ... from`. */
+  from?: string;
+  /** Local binding when it differs from the exported name. */
+  local?: string;
+  line: number;
+}
+
+export interface FunctionEntry {
+  /** `name`, `Class.method`, `object.key`, or `METHOD /path` for route handlers. */
+  name: string;
+  kind: 'function' | 'arrow' | 'method' | 'constructor' | 'getter' | 'setter' | 'route-handler';
+  async: boolean;
+  generator: boolean;
+  static?: true;
+  params: string[];
+  line: number;
+  endLine: number;
+  lines: number;
+  exported: boolean;
+  /** First sentence of the JSDoc description, if there is one. */
+  doc?: string;
+  /** Approximate cyclomatic complexity (1 + branches). */
+  complexity: number;
+  /** Deepest nesting of control-flow statements. */
+  maxNesting: number;
+  /** Unique call targets, excluding `require` and `console.*`. */
+  calls: string[];
+  /** The subset of `calls` that resolve to functions defined in this file. */
+  localCalls: string[];
+}
+
+export interface ClassEntry {
+  name: string;
+  extends: string | null;
+  line: number;
+  endLine: number;
+  methods: Array<{
+    name: string;
+    kind: 'function' | 'arrow' | 'method' | 'constructor' | 'getter' | 'setter';
+    static: boolean;
+    async: boolean;
+  }>;
+  exported: boolean;
+}
+
+export interface RouteEntry {
+  method: string;
+  path: string;
+  handler: string;
+  middleware?: string[];
+  line: number;
+}
+
+export type SideEffectType =
+  | 'server-listen'
+  | 'server-create'
+  | 'connection'
+  | 'env-load'
+  | 'process-handler'
+  | 'process-exit'
+  | 'timer'
+  | 'filesystem'
+  | 'child-process'
+  | 'console-output'
+  | 'global-mutation'
+  | 'top-level-await';
+
+export interface SideEffectEntry {
+  type: SideEffectType;
+  detail?: string;
+  line: number;
+}
+
+export interface EnvEntry {
+  name: string;
+  line: number;
+  /** True if some use supplies a fallback (`||`, `??` or a destructuring default). */
+  hasDefault: boolean;
+}
+
+export interface AnalysisResult {
+  schemaVersion: 1;
+  file: string | null;
+  moduleType: 'esm' | 'commonjs';
+  stats: {
+    lines: number;
+    imports: number;
+    exports: number;
+    functions: number;
+    classes: number;
+    routes: number;
+  };
+  /** A short, plain-language description assembled from the fields below. */
+  summary: string;
+  dependencies: { builtin: string[]; packages: string[]; local: string[] };
+  imports: ImportEntry[];
+  exports: ExportEntry[];
+  functions: FunctionEntry[];
+  classes: ClassEntry[];
+  routes: RouteEntry[];
+  sideEffects: SideEffectEntry[];
+  env: EnvEntry[];
+}
+
+export declare class ParseError extends Error {
+  name: 'ParseError';
+  /** 1-based. */
+  line?: number;
+  /** 1-based. */
+  column?: number;
+}
+
+export declare function analyze(code: string, options?: AnalyzeOptions): AnalysisResult;
+export declare function analyzeFile(path: string, options?: Omit<AnalyzeOptions, 'filename'>): Promise<AnalysisResult>;