rolldown-plugin-angularjs-annotate 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Gilles Piou
+Copyright (c) 2013-2016 Olov Lassus <olov.lassus@gmail.com>
+
+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/NOTICE

@@ -0,0 +1,16 @@
+This project includes an independent ESTree/MagicString adaptation of matching
+behavior and tests from:
+
+- babel-plugin-angularjs-annotate by schmod
+  https://github.com/schmod/babel-plugin-angularjs-annotate
+- ng-annotate by Olov Lassus and contributors
+  https://github.com/olov/ng-annotate
+
+The original ng-annotate copyright is:
+
+  Copyright (c) 2013-2016 Olov Lassus <olov.lassus@gmail.com>
+
+Both upstream projects are distributed under the MIT License. The upstream
+copyright is retained in this project's LICENSE. The development test suite
+loads the published babel-plugin-angularjs-annotate@0.10.0 fixtures directly;
+those fixture files are not included in this package's published files.

package/README.md

@@ -0,0 +1,128 @@
+# rolldown-plugin-angularjs-annotate
+
+AngularJS dependency-injection annotations for Rolldown, without a Babel
+transform layer.
+
+This package ports the supported annotation behavior of
+`babel-plugin-angularjs-annotate@0.10.0` to Rolldown. Its complete active corpus
+of 131 fixtures across 11 suites is checked in the upstream project's enabled
+original-source and Babel-transpiled ES5 modes, including context-sensitive
+negative cases and `explicitOnly`.
+
+## Install
+
+Requires Node.js `>=22.12.0` and Rolldown `^1.2.0`.
+
+```sh
+npm install --save-dev rolldown-plugin-angularjs-annotate
+```
+
+## Usage
+
+```js
+const angularjsAnnotate = require('rolldown-plugin-angularjs-annotate');
+
+module.exports = {
+  plugins: [angularjsAnnotate()]
+};
+```
+
+The plugin uses Rolldown's filtered transform hook and native AST/MagicString
+metadata when available. It runs in the `post` phase so framework plugins can
+turn virtual modules, such as Vue single-file component scripts, into
+JavaScript first.
+
+This is a Rolldown plugin. Its package metadata deliberately marks Rollup as
+incompatible rather than claiming support for an untested fallback host.
+
+## Options
+
+```js
+angularjsAnnotate({
+  include: ['**/src/**/*.js', '**/src/**/*.ts'],
+  exclude: '**/*.spec.js',
+  explicitOnly: false,
+  regexp: '^app(?:\\..+)?$'
+});
+```
+
+| Option | Meaning |
+| --- | --- |
+| `include` | String glob, `RegExp`, or array of either. Defaults to JavaScript/TypeScript IDs and modules Rolldown identifies as JavaScript/TypeScript, including framework-generated virtual modules. |
+| `exclude` | String glob, `RegExp`, or array of either. Defaults to `node_modules` and Rolldown's runtime module. |
+| `explicitOnly` | When `true`, only `@ngInject`, `ngInject`, and their no-inject counterparts are considered. |
+| `regexp` | Restricts source expressions accepted as implicit module receivers, such as `app` or `require("app-module")`. Explicit `angular.module(...)` chains remain recognized. The compatibility default accepts identifier and dotted-property forms. |
+
+Use `regexp: '^$'` to disable implicit receiver matching while retaining explicit
+`angular.module(...)` chains.
+
+## Supported annotations
+
+Explicit annotation supports:
+
+- `@ngInject` and `@ngNoInject` line, block, and JSDoc comments
+- `"ngInject"` and `"ngNoInject"` directive prologues
+- `ngInject(value)` and `ngNoInject(value)` wrappers
+- functions, arrows, classes, constructors, assignments, references, exports,
+  object properties, and recursively annotated object literals
+
+Implicit matching supports:
+
+- long and short AngularJS module registrations and chains
+- controllers, services, factories, filters, directives, providers,
+  decorators, animations, components, config/run blocks, invoke, and store
+- component controllers/templates and directive definition objects
+- provider `$get` declarations and reference following
+- `$provide`, `$injector`, `$controllerProvider`, route/UI-Router providers,
+  HTTP interceptors, UI Bootstrap modals, and Angular Material overlays
+- lexical binding resolution, shadowing, hoisting, aliases, and direct IIFEs
+
+Existing inline arrays, `$inject` assignments, and static class `$inject`
+fields are preserved. Unsupported destructured parameter lists are left
+unchanged instead of producing positionally incorrect annotations. Ambiguous
+mutable references and object methods that rely on `super` are also left
+unchanged rather than receiving a transformation that could alter runtime
+semantics.
+
+## Low-level API
+
+Pipelines sharing an AST and MagicString instance can call the core directly:
+
+```js
+const { annotate } = require('rolldown-plugin-angularjs-annotate');
+
+annotate(program, code, magicString, {
+  comments,
+  explicitOnly: false
+});
+```
+
+The `comments` array is optional; the core has a source-based fallback for
+native Rolldown ASTs. Public TypeScript declarations cover both the plugin and
+the low-level API. `onWarn` receives a message and, when available, a diagnostic
+with zero-based `start` and `end` source offsets. The plugin wrapper forwards
+these as structured Rolldown warnings with the module ID and source position;
+annotation and parser failures similarly use Rolldown's structured error API.
+
+## Verification
+
+```sh
+npm run check
+```
+
+The suite includes 508 semantic comparisons against the upstream compatibility
+corpus, safety regressions, a minified AngularJS `strictDi` bootstrap, source
+maps, filters, TypeScript/Vue module IDs, framework-generated modules with
+non-script IDs, package consumer types, and real Rolldown builds with native
+MagicString both disabled and enabled. Babel is a development-only fixture
+preprocessor for the ES5 compatibility lane; published transforms use
+Rolldown's parser and do not add a Babel transform layer.
+
+## AI disclosure
+
+Developed entirely with OpenAI Codex (GPT-5.6 Sol, using Ultra and Extra High
+reasoning effort).
+
+## License
+
+MIT. See [NOTICE](NOTICE) for upstream attribution.

package/index.d.ts

@@ -0,0 +1,59 @@
+import type MagicString from 'magic-string';
+import type { Plugin, RolldownMagicString } from 'rolldown';
+import type { ESTree } from 'rolldown/utils';
+
+declare function angularjsAnnotate(
+  options?: angularjsAnnotate.AngularJSAnnotateOptions,
+): Plugin;
+
+declare namespace angularjsAnnotate {
+  type FilterPattern = string | RegExp | readonly (string | RegExp)[];
+
+  interface AngularJSAnnotateOptions {
+    /** Module IDs transformed by the plugin. */
+    include?: FilterPattern;
+    /** Module IDs omitted by the plugin. */
+    exclude?: FilterPattern;
+    /** Disable all implicit AngularJS pattern matching. */
+    explicitOnly?: boolean;
+    /** Restrict source expressions accepted as implicit AngularJS module receivers. */
+    regexp?: string | RegExp;
+  }
+
+  interface ParserComment {
+    /** Accepted for compatibility with parser comment objects; annotation only uses the range and value. */
+    type?: string;
+    value: string;
+    start: number;
+    end: number;
+  }
+
+  interface AnnotateDiagnostic {
+    /** Stable diagnostic identifier suitable for filtering build logs. */
+    code?: string;
+    /** Zero-based source offsets when the diagnostic is tied to syntax. */
+    start?: number;
+    end?: number;
+  }
+
+  interface AnnotateOptions {
+    comments?: readonly ParserComment[] | null;
+    explicitOnly?: boolean;
+    regexp?: string | RegExp;
+    /** Receives the message and, when available, its source span. */
+    onWarn?: (message: string, diagnostic?: AnnotateDiagnostic) => void;
+  }
+
+  function annotate(
+    program: ESTree.Program,
+    code: string,
+    magicString: MagicString | RolldownMagicString,
+    options?: AnnotateOptions,
+  ): void;
+
+  const angularjsAnnotate: (
+    options?: AngularJSAnnotateOptions,
+  ) => Plugin;
+}
+
+export = angularjsAnnotate;

package/index.js

@@ -0,0 +1,103 @@
+'use strict';
+
+const MagicString = require('magic-string');
+const { parseSync } = require('rolldown/utils');
+const annotate = require('./src/annotate');
+
+const DEFAULT_EXCLUDE = [/(?:^|[/\\])node_modules[/\\]/, /\0rolldown[/\\]runtime\.js$/];
+
+function angularjsAnnotate(options = {}) {
+  const { include, exclude = DEFAULT_EXCLUDE } = options;
+  const useModuleTypeFilter = include === undefined;
+
+  return {
+    name: 'rolldown-plugin-angularjs-annotate',
+    enforce: 'post',
+    transform: {
+      filter: useModuleTypeFilter ? {
+        id: { exclude },
+        moduleType: ['js', 'jsx', 'ts', 'tsx'],
+      } : { id: { include, exclude } },
+      handler(code, id, meta = {}) {
+        let parsed;
+        try {
+          parsed = meta.ast ? { program: meta.ast, comments: null, errors: [] } : parseSync(id, code, {
+            lang: language(id, meta.moduleType),
+            sourceType: 'unambiguous',
+          });
+        } catch (error) {
+          reportError(this, error, id);
+        }
+        if (parsed.errors.length) reportError(this, parserError(parsed.errors[0], id), id);
+
+        const magicString = meta.magicString || new MagicString(code);
+        try {
+          annotate(parsed.program, code, magicString, {
+            comments: parsed.comments,
+            explicitOnly: options.explicitOnly,
+            regexp: options.regexp,
+            onWarn: (message, diagnostic) => {
+              if (typeof this?.warn !== 'function') return;
+              this.warn({
+                message,
+                id,
+                pluginCode: diagnostic?.code || 'ANNOTATION_MISMATCH',
+              }, diagnosticPosition(diagnostic));
+            },
+          });
+        } catch (error) {
+          reportError(this, error, id);
+        }
+        if (!magicString.hasChanged()) return;
+
+        return meta.magicString ? { code: magicString } : {
+          code: magicString.toString(),
+          map: magicString.generateMap({ hires: 'boundary', includeContent: true, source: id }),
+        };
+      },
+    },
+  };
+}
+
+function language(id, moduleType) {
+  if (isJavaScriptModuleType(moduleType)) return moduleType;
+  const match = /(?:\.([cm]?[jt]sx?)(?:$|\?)|(?:^|[?&])lang\.([jt]sx?)(?:&|$))/.exec(id);
+  const extension = match?.[1] || match?.[2];
+  if (extension?.endsWith('tsx')) return 'tsx';
+  if (extension?.endsWith('ts')) return 'ts';
+  if (extension?.endsWith('jsx')) return 'jsx';
+  return 'js';
+}
+
+function isJavaScriptModuleType(moduleType) {
+  return moduleType === 'js' || moduleType === 'jsx' || moduleType === 'ts' || moduleType === 'tsx';
+}
+
+function parserError(diagnostic, id) {
+  const message = diagnostic?.message || diagnostic?.labels?.[0]?.message || String(diagnostic);
+  const error = new SyntaxError(message);
+  error.cause = diagnostic;
+  error.id = id;
+  error.pluginCode = 'PARSE_ERROR';
+  const position = diagnosticPosition(diagnostic);
+  if (position !== undefined) error.start = position;
+  return error;
+}
+
+function reportError(context, value, id) {
+  const error = value instanceof Error ? value : new Error(String(value));
+  if (error.id === undefined) error.id = id;
+  if (error.pluginCode === undefined) error.pluginCode = error.code || 'ANNOTATION_ERROR';
+  if (typeof context?.error === 'function') context.error(error, diagnosticPosition(error));
+  if (!error.message.startsWith(`${id}: `)) error.message = `${id}: ${error.message}`;
+  throw error;
+}
+
+function diagnosticPosition(diagnostic) {
+  const position = diagnostic?.start ?? diagnostic?.labels?.[0]?.start;
+  return Number.isInteger(position) && position >= 0 ? position : undefined;
+}
+
+module.exports = angularjsAnnotate;
+module.exports.annotate = annotate;
+module.exports.angularjsAnnotate = angularjsAnnotate;

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "rolldown-plugin-angularjs-annotate",
+  "version": "0.1.0",
+  "description": "AngularJS dependency injection annotations for Rolldown without a Babel transform layer",
+  "author": "Gilles Piou",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pioug/rolldown-plugin-angularjs-annotate.git"
+  },
+  "homepage": "https://github.com/pioug/rolldown-plugin-angularjs-annotate#readme",
+  "bugs": {
+    "url": "https://github.com/pioug/rolldown-plugin-angularjs-annotate/issues"
+  },
+  "type": "commonjs",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "require": "./index.js",
+      "default": "./index.js"
+    },
+    "./core": {
+      "types": "./src/annotate.d.ts",
+      "require": "./src/annotate.js",
+      "default": "./src/annotate.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "NOTICE",
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "test:parity": "node --test test/parity.test.js",
+    "test:unit": "node --test test/annotate.test.js test/angular-aliases.test.js test/binding-resolution.test.js test/markers.test.js test/nested-targets.test.js test/plugin.test.js test/typescript.test.js",
+    "typecheck": "tsc -p type-tests/tsconfig.json",
+    "lint:package": "publint",
+    "verify:package-contents": "node scripts/verify-package-contents.js",
+    "check": "npm run typecheck && npm test && npm run lint:package",
+    "prepublishOnly": "npm run check && npm run verify:package-contents"
+  },
+  "keywords": [
+    "angularjs",
+    "dependency-injection",
+    "ng-annotate",
+    "rolldown",
+    "rolldown-plugin"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "dependencies": {
+    "magic-string": "^0.30.21"
+  },
+  "peerDependencies": {
+    "rolldown": "^1.2.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.29.7",
+    "@babel/preset-env": "^7.29.7",
+    "angular": "1.8.3",
+    "babel-plugin-angularjs-annotate": "0.10.0",
+    "publint": "^0.3.21",
+    "rolldown": "^1.2.0",
+    "typescript": "^5.9.3"
+  },
+  "compatiblePackages": {
+    "schemaVersion": 1,
+    "rollup": {
+      "type": "incompatible",
+      "reason": "Targets and tests Rolldown only and depends on Rolldown parser and plugin APIs"
+    }
+  }
+}

package/src/annotate.d.ts

@@ -0,0 +1,3 @@
+import angularjsAnnotate = require('../index');
+
+export = angularjsAnnotate.annotate;