mlreps 0.1.0

package/LICENSE.md

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Krish Trivedi
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -0,0 +1,108 @@
+# mlreps
+
+Reads a repository and reports what a change to it would reach — the files, the symbols, the edges
+between them, and what our rules found. It runs in your pipeline, on a checkout that is already
+there.
+
+**It never sends your source.** What leaves is the graph the scan built: paths, line numbers,
+symbol names, route URLs and package names. There is no column in our database that could hold a
+diff, and a build gate fails if somebody adds a place for one.
+
+## Two ways to use it, and they are different decisions
+
+### On a pull request, sending us nothing
+
+```yaml
+name: Codebase intelligence
+
+on:
+  pull_request:
+
+# Without this, GITHUB_TOKEN cannot write a check run and every run ends in a 403.
+permissions:
+  contents: read
+  checks: write
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm ci
+      - run: npx mlreps check .
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # On a pull request, GITHUB_SHA is a merge commit that exists nowhere in
+          # the repository — a check run posted against it is invisible.
+          PLATFORM_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+```
+
+The analysis happens on your runner and the check run is posted to your repository by your own CI
+token. Nothing of yours leaves and no credential of ours is involved. This is the stronger of the
+two arrangements, and it costs you the dashboard.
+
+### On the default branch, publishing to your dashboard
+
+```yaml
+name: MLReps
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Without this the scan reports that every file was never committed.
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - run: npm ci
+      - run: npx mlreps scan . --publish
+        env:
+          MLREPS_KEY: ${{ secrets.MLREPS_KEY }}
+```
+
+Make a key at https://www.mlreps.com/start and set it as the repository secret `MLREPS_KEY`. It runs
+on `push` rather than on pull requests on purpose: a report published from every branch would make
+your dashboard a picture of whichever job finished last.
+
+## Anywhere else
+
+```
+MLREPS_KEY=mlrp_…
+MLREPS_ENDPOINT=https://www.mlreps.com
+```
+
+```
+npx mlreps scan .              # analyse, print, send nothing
+npx mlreps scan . --publish    # and send the graph to your dashboard
+npx mlreps scan . --publish --dry-run
+npx mlreps impact --base main  # what this branch's change reaches
+npx mlreps check .             # a check run on this pull request
+```
+
+## It will not break your build
+
+Every command exits 0, including when we are unreachable. A tool that turns a build red because it
+disagreed with itself is a tool that gets removed from the pipeline the same afternoon. Ask for a
+gate explicitly with `--fail-on-exposed`.
+
+## Licence
+
+[FSL-1.1-ALv2](./LICENSE.md) — the Functional Source License. You may use, read and modify this for
+anything except a product that competes with it, and every version becomes Apache-2.0 two years after
+it is released. Being able to read exactly what runs in your pipeline is the point.
+
+## What it can read
+
+TypeScript and JavaScript. A repository it resolves below 70% is declined rather than half-drawn,
+and every screen and every run prints how much of the call sites it could follow — a region we could
+not read is never shown as a region with nothing wrong in it.