@causalmap/filter-engine 0.1.0

package/LICENSE.md

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Causal Map Ltd
+
+## 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 MIT license 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 MIT license, in which case the following will apply:
+
+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

@@ -0,0 +1,121 @@
+# @causalmap/filter-engine
+
+Pure, dependency-free link-filter engine for causal maps. Give it a list of links and an ordered
+list of filter configs; get the filtered links back. No DOM, no database, no framework. Plain ES
+modules, Node 18+ or any modern browser.
+
+This is the filtering core extracted from [Causal Map](https://causalmap.app). The code under
+`src/` is a snapshot of the app's canonical engine, so its behaviour tracks the live product.
+
+## Licence
+
+Source-available under the [Functional Source License 1.1 (FSL-1.1-MIT)](./LICENSE.md): free to use,
+copy, modify and redistribute for any purpose except a competing use, that is, putting it into a
+product or service that substitutes for the Software or for Causal Map. Internal use, education,
+research and professional services are all permitted. Each release converts to the MIT licence two
+years after it is published. This is source-available rather than an OSI open-source licence until
+that conversion.
+
+## Install
+
+```sh
+npm install @causalmap/filter-engine
+```
+
+## Quick start
+
+```js
+import { applyOrderedLinkFilters } from '@causalmap/filter-engine'
+
+const links = [
+  { cause: 'training', effect: 'confidence', source_id: 's1', tags: 'outcome' },
+  { cause: 'confidence', effect: 'income', source_id: 's1', tags: 'impact' },
+  { cause: 'training', effect: 'income', source_id: 's2', tags: 'impact' },
+]
+
+const filters = [
+  { type: 'tags', selectedTags: ['impact'] },
+  { type: 'exclude-self-loops' },
+]
+
+const { rows, unsupported } = applyOrderedLinkFilters(links, filters /*, sources */)
+// rows = the surviving links, in order; unsupported = any filter types this build does not handle
+```
+
+`applyOrderedLinkFilters(links, filters, sources = [])` runs the filters in array order and returns
+`{ rows, unsupported }`. The optional third argument is the sources table (objects with at least
+`id`); it is only needed by filters that read source metadata.
+
+## The link object
+
+A link is a plain object. The fields the engine reads:
+
+- `cause`, `effect`: factor labels (strings). The core of every link.
+- `source_id`: which source the link came from; used by frequency and path-tracing counts.
+- `tags`: string (comma-separated) or array, used by the tag filters.
+- any other column you attach (for example `sentiment`, or flattened source-group columns): read by
+  the `everything` and `source-groups` filters via a resolved field name.
+
+Extra fields you put on a link are preserved through filtering.
+
+## Filters
+
+Each filter is `{ type, ...options }`. Set `enabled: false` to skip one. Supported types:
+
+| type | what it does | key options |
+|------|--------------|-------------|
+| `label` | keep links within N steps of factors matching a label | `selectedLabels`, `stepsUp`, `stepsDown`, `traceThreads` |
+| `exclude-label` | drop links whose cause/effect match labels | `selectedLabels`, `matchMode`, `excludeAny` |
+| `tags` | keep links matching any selected tag | `selectedTags`, `matchMode` |
+| `exclude-tags` | drop links matching selected tags | `selectedTags`, `matchMode`, `excludeAny` |
+| `path-tracing` | keep links on paths between two factor sets | see path tracing below |
+| `link-frequency` | keep the most or least frequent cause to effect pairs | `which`, `mode`, `threshold` |
+| `factor-frequency` | keep links whose factors are frequent enough | `which`, `mode`, `threshold` |
+| `combine-opposites` | merge negative variants into their positive label | sets `flipped_*` flags |
+| `zoom` | trim factor labels to a hierarchy level | `level` |
+| `collapse` | merge a set of labels into one | `selectedLabels` |
+| `replace-brackets` | rewrite bracketed label parts | |
+| `source-groups` | membership over a resolved source-group column | `selectedField`, `selectedValues` |
+| `everything` | membership over any resolved link column | `selectedField`, `selectedValues` |
+| `exclude-self-loops` | drop links where cause equals effect | |
+
+`matchMode` is `'start'` (default), `'anywhere'`, or `'exact'`. Frequency `mode` is `'top'`
+(default, keep the top `threshold` by count) or `'minimum'` (keep count at or above `threshold`);
+`which` is `'sources'` to count unique sources, otherwise it counts appearances.
+
+Per-filter functions are also exported if you want to drive them yourself
+(`applyTagsFilter`, `applyLinkFrequencyFilter`, `applyPathTracingFilter`, and so on).
+
+### Path tracing
+
+```js
+import { applyPathTracingFilter } from '@causalmap/filter-engine'
+```
+
+Keeps links lying on paths from one factor set to another within a step budget. Highlight helpers
+`matchPathFactors` and `tracePaths` are exported alongside it.
+
+## Reserved output fields
+
+Some filters write fields onto the returned links. Do not strip these if you render downstream:
+
+- `_recoded`: `{ cause: { original, recoded }, effect: {...} }`, set by zoom/collapse/replace-brackets; the earliest original is preserved. Used to display a renamed factor.
+- `_recoded_cause` / `_recoded_effect`: booleans, set by collapse and replace-brackets only.
+- `flipped_cause` / `flipped_effect`: booleans, set by combine-opposites and read by link-frequency bundling.
+
+## Host-resolved inputs
+
+A few filters need a value the host application resolves and supplies:
+
+- `everything` / `source-groups` read `link[filter.selectedField]`, so set `selectedField` to a real
+  column before running (the app resolves friendly names to columns like `sentiment` or `s_region`).
+- `link-frequency` bundling can separate flipped opposite pairs. Pass
+  `applyLinkFrequencyFilter(links, filter, { separateFlippedBundles })` when driving it directly. It
+  defaults to `false`, so a consumer without combine-opposites needs nothing.
+
+## Provenance
+
+Canonical source: `webapp/js/filter-engine` in the Causal Map app. `src/` here is generated by
+`sync-from-webapp.mjs` and regenerated on every publish. The test suite under `tests/` (run with
+`npm test`) includes the app's differential harnesses, which check this engine against a faithful
+copy of the app's filter logic across thousands of configurations.

package/index.js

@@ -0,0 +1,38 @@
+// Public surface of @causalmap/filter-engine.
+//
+// The code under ./src is a generated snapshot of the canonical engine in the
+// causal-map-extension webapp (webapp/js/filter-engine + two pure deps). Do not
+// edit ./src by hand; run `npm run sync` to refresh it. This file is the authored
+// public API and is the one place to widen or narrow what consumers can import.
+
+// Primary entry: ordered structural link filtering, data in and data out.
+export { applyOrderedLinkFilters } from './src/apply-filters.js'
+
+// Per-filter functions, for consumers that drive filters individually.
+export {
+  applyLabelFilter,
+  applyTagsFilter,
+  applyExcludeTagsFilter,
+  applyExcludeLabelFilter,
+  applyEverythingFilter,
+  applySourceGroupsFilter,
+  applyExcludeSelfLoops,
+  applyLinkFrequencyFilter,
+  applyFactorFrequencyFilter,
+  applyZoomFilter,
+  applyCollapseFilter,
+  applyReplaceBracketsFilter,
+  applyRecodingTransform,
+  applyZoomToLabel,
+  applyCollapseToLabel,
+  applyCombineOppositesFilter,
+  // Highlight helper: which factors a label filter matched.
+  matchLabelFactors,
+} from './src/apply-filters.js'
+
+// Path tracing and its highlight/trace helpers.
+export {
+  applyPathTracingFilter,
+  matchPathFactors,
+  tracePaths,
+} from './src/path-tracing.js'

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@causalmap/filter-engine",
+  "version": "0.1.0",
+  "description": "Pure, dependency-free link-filter engine for causal maps: ordered structural filters (tags, label, path-tracing, frequency, combine-opposites, zoom/collapse and more), data in and data out.",
+  "type": "module",
+  "license": "FSL-1.1-MIT",
+  "author": "Causal Map Ltd",
+  "homepage": "https://causalmap.app",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "src/",
+    "LICENSE.md",
+    "README.md"
+  ],
+  "scripts": {
+    "sync": "node ./sync-from-webapp.mjs",
+    "test": "node --test tests/filters/traversal.test.mjs tests/filters/ordered-filters.test.mjs && node tests/filters/_filtering-diff.mjs && node tests/filters/_transform-diff.mjs && node tests/filters/_combine-diff.mjs && node tests/filters/_frequency-diff.mjs && node tests/filters/_path-diff.mjs",
+    "prepack": "node ./sync-from-webapp.mjs"
+  },
+  "keywords": [
+    "causal-map",
+    "causal-mapping",
+    "filter",
+    "graph",
+    "qualitative-data"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}