@mark1russell7/conventions 0.12.3 → 0.13.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1321,11 +1321,7 @@ const pinnedGitDeps = {
1321
1321
  return breaks;
1322
1322
  }
1323
1323
  };
1324
- // src/rules/release-files.ts
1325
- /**
1326
- * The rule `release-files`: a pull request changes a file of the release flow only with a reason
1327
- * that everyone can see.
1328
- */
1324
+ // src/change.ts
1329
1325
  /** This function gives the range of the change: the option `--base`, or the merge commit of a pull request. */
1330
1326
  function rangeOf(context) {
1331
1327
  if (context.base !== void 0) {
@@ -1361,6 +1357,28 @@ function rangeOf(context) {
1361
1357
  ends: ["HEAD^1", "HEAD^2"]
1362
1358
  };
1363
1359
  }
1360
+ /**
1361
+ * This function gives the files that the change adds, relative to the root, with `/`. A renamed file is not added.
1362
+ * With no change (no base and no pull request), it gives undefined.
1363
+ */
1364
+ function addedFiles(context) {
1365
+ const range = rangeOf(context);
1366
+ if ("skipped" in range) return void 0;
1367
+ const out = context.git([
1368
+ "diff",
1369
+ "--name-only",
1370
+ "--find-renames",
1371
+ "--diff-filter=A",
1372
+ ...range.diff
1373
+ ]);
1374
+ if (out === void 0) return void 0;
1375
+ return new Set(out.split(/\r?\n/).filter((file) => file !== ""));
1376
+ }
1377
+ // src/rules/release-files.ts
1378
+ /**
1379
+ * The rule `release-files`: a pull request changes a file of the release flow only with a reason
1380
+ * that everyone can see.
1381
+ */
1364
1382
  /** This function gives the pull request of the event file of GitHub Actions. With no event file, the body is empty. */
1365
1383
  function pullRequestOf(context) {
1366
1384
  const file = context.env["GITHUB_EVENT_PATH"];
@@ -3556,6 +3574,610 @@ const RULES = [
3556
3574
  runnerBudget,
3557
3575
  gateTrigger
3558
3576
  ];
3577
+ // src/map.ts
3578
+ /** The rule of the map. Each session and each review applies it. */
3579
+ const MAP_RULE = "Before you write a helper, find its home in this map. If the home does not have the function, add it to the home, in a pull request of the home repository. Do not make a local copy, a new package or a new repository for an area that has a home: that needs the strategist. A home that is not on npm is used with workspace:* or a github: specifier pinned to a commit. If no area fits, ask the strategist for a home before you write the code.";
3580
+ /** The public homes. Each package of the fleet that other code can use has one area. */
3581
+ const HOMES = [
3582
+ {
3583
+ area: "statistics",
3584
+ title: "Statistics",
3585
+ covers: "quantiles, medians, means, SD, bootstrap intervals, sign and permutation tests, Holm, Wilson, Brier, calibration, correlation, noise floors",
3586
+ packages: ["@mark1russell7/rigor-statistics"],
3587
+ repo: "mark1russell7/rigor",
3588
+ state: "published",
3589
+ words: [
3590
+ "stats",
3591
+ "quantile",
3592
+ "median",
3593
+ "mean",
3594
+ "percentile",
3595
+ "bootstrap",
3596
+ "interval",
3597
+ "confidence",
3598
+ "p-value",
3599
+ "brier",
3600
+ "wilson",
3601
+ "holm",
3602
+ "spearman",
3603
+ "kendall",
3604
+ "noise"
3605
+ ]
3606
+ },
3607
+ {
3608
+ area: "random",
3609
+ title: "Seeded random and generated inputs",
3610
+ covers: "seeded random numbers, seeds from names, hashes for seeds, draws, input families with dimensions and ranges",
3611
+ packages: ["@mark1russell7/rigor-generators"],
3612
+ repo: "mark1russell7/rigor",
3613
+ state: "published",
3614
+ words: [
3615
+ "seed",
3616
+ "prng",
3617
+ "mulberry32",
3618
+ "fnv",
3619
+ "hash",
3620
+ "shuffle",
3621
+ "sample",
3622
+ "fixture",
3623
+ "generator"
3624
+ ]
3625
+ },
3626
+ {
3627
+ area: "bench",
3628
+ title: "Benchmarks and speed gates",
3629
+ covers: "the bench harness: a fresh process per case, the order turned each round, A/A pairs, the CPU model, paired-time records, speed gates, determinism gates",
3630
+ packages: [],
3631
+ repo: "mark1russell7/rigor",
3632
+ state: "planned",
3633
+ words: [
3634
+ "benchmark",
3635
+ "harness",
3636
+ "timing",
3637
+ "perf",
3638
+ "gate",
3639
+ "paired-time",
3640
+ "a/a",
3641
+ "warm-up"
3642
+ ],
3643
+ note: "Five repositories have their own harness today (vex, packing, highways, layout-stack, typeset). Do not grow a local harness: the shared one replaces them."
3644
+ },
3645
+ {
3646
+ area: "test-generation",
3647
+ title: "Test helpers and test generation",
3648
+ covers: "property tests on fast-check, pairwise and covering arrays, metamorphic relations, chaos and load schedules, shared test fixtures",
3649
+ packages: [],
3650
+ repo: "mark1russell7/rigor",
3651
+ state: "planned",
3652
+ words: [
3653
+ "test",
3654
+ "testing",
3655
+ "property",
3656
+ "fast-check",
3657
+ "arbitrary",
3658
+ "pairwise",
3659
+ "metamorphic",
3660
+ "chaos",
3661
+ "load",
3662
+ "fake"
3663
+ ],
3664
+ note: "@mark1russell7/vex-testkit is only for Vex domains. A fake shell for tests is in @procedures/shell."
3665
+ },
3666
+ {
3667
+ area: "exact-math",
3668
+ title: "Expressions and exact arithmetic",
3669
+ covers: "expression documents, exact rationals, floats with error bounds, intervals, robust geometric predicates (orientation, in-circle)",
3670
+ packages: ["@mark1russell7/expression"],
3671
+ repo: "mark1russell7/algebra",
3672
+ state: "unpublished",
3673
+ words: [
3674
+ "math",
3675
+ "arithmetic",
3676
+ "rational",
3677
+ "bigint",
3678
+ "interval",
3679
+ "error bound",
3680
+ "predicate",
3681
+ "orientation",
3682
+ "symbolic",
3683
+ "exact"
3684
+ ],
3685
+ note: "Statistics go to rigor-statistics, and geometry records go to layout-contract. There is no math package."
3686
+ },
3687
+ {
3688
+ area: "units",
3689
+ title: "Amounts with units",
3690
+ covers: "amounts in typed units, exact conversion factors between units",
3691
+ packages: ["@mark1russell7/quantity"],
3692
+ repo: "mark1russell7/systems",
3693
+ state: "published",
3694
+ words: [
3695
+ "unit",
3696
+ "quantity",
3697
+ "duration",
3698
+ "bytes",
3699
+ "conversion"
3700
+ ]
3701
+ },
3702
+ {
3703
+ area: "state-machines",
3704
+ title: "State machines and timers",
3705
+ covers: "state machines as data, closed forms of their timers, failure detection, recovery and trace replay",
3706
+ packages: ["@mark1russell7/algebra"],
3707
+ repo: "mark1russell7/systems",
3708
+ state: "published",
3709
+ words: [
3710
+ "state machine",
3711
+ "timer",
3712
+ "timeout",
3713
+ "heartbeat",
3714
+ "failover",
3715
+ "detection"
3716
+ ],
3717
+ note: "The npm name @mark1russell7/algebra is this package of systems, not the algebra repository."
3718
+ },
3719
+ {
3720
+ area: "service",
3721
+ title: "Services and servers",
3722
+ covers: "a service declared as data, its lifecycle and checks, jittered loops, clocks, backoff and retries (service); the HTTP, WebSocket and MCP host of procedures (peer)",
3723
+ packages: ["@mark1russell7/service", "@procedures/peer"],
3724
+ repo: "mark1russell7/systems",
3725
+ state: "published",
3726
+ words: [
3727
+ "server",
3728
+ "http server",
3729
+ "lifecycle",
3730
+ "shutdown",
3731
+ "health",
3732
+ "loop",
3733
+ "clock",
3734
+ "backoff",
3735
+ "retry",
3736
+ "jitter",
3737
+ "websocket"
3738
+ ],
3739
+ note: "A server package is made with the template preset service. @procedures/peer is in mark1russell7/client."
3740
+ },
3741
+ {
3742
+ area: "procedures",
3743
+ title: "Typed calls and MCP tools",
3744
+ covers: "procedures as data: one typed call model in process, over HTTP, WebSocket, CLI and MCP, with streaming and middleware",
3745
+ packages: [
3746
+ "@procedures/client",
3747
+ "@procedures/mcp-server",
3748
+ "@procedures/compiler"
3749
+ ],
3750
+ repo: "mark1russell7/client",
3751
+ state: "published",
3752
+ words: [
3753
+ "rpc",
3754
+ "procedure",
3755
+ "mcp",
3756
+ "tool",
3757
+ "middleware",
3758
+ "api client"
3759
+ ]
3760
+ },
3761
+ {
3762
+ area: "system-io",
3763
+ title: "Files, commands, git, GitHub and npm",
3764
+ covers: "atomic file and JSON writes, globs, safe commands with argv and no shell, git, the GitHub CLI and API, npm registry lookups, HTTP requests, JSON, YAML and CSV, environment variables",
3765
+ packages: [
3766
+ "@procedures/fs",
3767
+ "@procedures/shell",
3768
+ "@procedures/git",
3769
+ "@procedures/gh",
3770
+ "@procedures/npm",
3771
+ "@procedures/http",
3772
+ "@procedures/json",
3773
+ "@procedures/env"
3774
+ ],
3775
+ repo: "mark1russell7/client",
3776
+ state: "published",
3777
+ words: [
3778
+ "file",
3779
+ "atomic",
3780
+ "write",
3781
+ "spawn",
3782
+ "exec",
3783
+ "shell",
3784
+ "command",
3785
+ "github",
3786
+ "registry",
3787
+ "fetch",
3788
+ "yaml",
3789
+ "csv",
3790
+ "env"
3791
+ ]
3792
+ },
3793
+ {
3794
+ area: "cli",
3795
+ title: "Command-line arguments",
3796
+ covers: "argument parsing and the help text of command-line tools, from a schema",
3797
+ packages: [],
3798
+ repo: "mark1russell7/client",
3799
+ state: "planned",
3800
+ words: [
3801
+ "argv",
3802
+ "arguments",
3803
+ "flags",
3804
+ "options",
3805
+ "parser",
3806
+ "help text",
3807
+ "command line"
3808
+ ],
3809
+ note: "Nine hand-written parsers exist (10-25). Until the library is ready, use @procedures/cli-run or keep the parser small."
3810
+ },
3811
+ {
3812
+ area: "data-structures",
3813
+ title: "Collections and graphs of dependencies",
3814
+ covers: "lists, deques, maps, trees and heaps; DAGs, cycles, topological order",
3815
+ packages: ["@procedures/collections", "@procedures/dag"],
3816
+ repo: "mark1russell7/client",
3817
+ state: "published",
3818
+ words: [
3819
+ "list",
3820
+ "queue",
3821
+ "deque",
3822
+ "heap",
3823
+ "tree map",
3824
+ "graph",
3825
+ "dag",
3826
+ "topological",
3827
+ "cycle"
3828
+ ]
3829
+ },
3830
+ {
3831
+ area: "optional",
3832
+ title: "Optional values",
3833
+ covers: "a value that is present or absent, with the functor and monad laws",
3834
+ packages: ["@mark1russell7/optional"],
3835
+ repo: "mark1russell7/optional",
3836
+ state: "published",
3837
+ words: [
3838
+ "option",
3839
+ "maybe",
3840
+ "some",
3841
+ "none",
3842
+ "monad",
3843
+ "functor"
3844
+ ],
3845
+ note: "@mark1russell7/render-optional is a second copy. It moves to @mark1russell7/optional."
3846
+ },
3847
+ {
3848
+ area: "geometry",
3849
+ title: "Geometry and layout records",
3850
+ covers: "points, boxes, segments, tolerances, the input and record formats of the layout engines, converters",
3851
+ packages: ["@mark1russell7/layout-contract"],
3852
+ repo: "mark1russell7/layout-contract",
3853
+ state: "published",
3854
+ words: [
3855
+ "point",
3856
+ "rect",
3857
+ "box",
3858
+ "segment",
3859
+ "polygon",
3860
+ "tolerance",
3861
+ "overlap",
3862
+ "intersection",
3863
+ "bounds"
3864
+ ],
3865
+ note: "Exact predicates go to algebra. @mark1russell7/vex-domains has 2D vectors for Vex formulas only."
3866
+ },
3867
+ {
3868
+ area: "packing",
3869
+ title: "Rectangle packing",
3870
+ covers: "shelf, guillotine, skyline and max-rects strategies, push cascades, measures of a placement",
3871
+ packages: ["@mark1russell7/packing"],
3872
+ repo: "mark1russell7/packing",
3873
+ state: "published",
3874
+ words: [
3875
+ "pack",
3876
+ "bin packing",
3877
+ "placement",
3878
+ "rectangles",
3879
+ "fill"
3880
+ ]
3881
+ },
3882
+ {
3883
+ area: "edge-routing",
3884
+ title: "Edge routing",
3885
+ covers: "edge routers for node-link diagrams: trunks, bundles, plugs and zoom levels",
3886
+ packages: ["@mark1russell7/highways"],
3887
+ repo: "mark1russell7/highways",
3888
+ state: "published",
3889
+ words: [
3890
+ "edge",
3891
+ "route",
3892
+ "bundle",
3893
+ "path",
3894
+ "orthogonal",
3895
+ "spline"
3896
+ ]
3897
+ },
3898
+ {
3899
+ area: "graph-layout",
3900
+ title: "Graph and tree layout",
3901
+ covers: "a layout for each container of a graph or tree, with boxes and routed edges for any renderer",
3902
+ packages: ["ireko"],
3903
+ repo: "mark1russell7/ireko",
3904
+ state: "published",
3905
+ words: [
3906
+ "layout",
3907
+ "tree layout",
3908
+ "radial",
3909
+ "force",
3910
+ "hierarchy",
3911
+ "container"
3912
+ ]
3913
+ },
3914
+ {
3915
+ area: "text",
3916
+ title: "Text measurement and line breaking",
3917
+ covers: "Unicode segmentation, text widths from font tables, line breaking, incremental relayout after edits",
3918
+ packages: [],
3919
+ repo: "mark1russell7/typeset",
3920
+ state: "planned",
3921
+ words: [
3922
+ "string",
3923
+ "unicode",
3924
+ "grapheme",
3925
+ "font",
3926
+ "width",
3927
+ "measure text",
3928
+ "line break",
3929
+ "wrap",
3930
+ "hyphen"
3931
+ ],
3932
+ note: "Plain string helpers (case, padding, templates) have no home yet: ask the strategist."
3933
+ },
3934
+ {
3935
+ area: "language-kernel",
3936
+ title: "Declarative languages",
3937
+ covers: "documents in envelopes, evaluators found by a ladder, parsers, incremental schedulers",
3938
+ packages: ["@mark1russell7/coeval"],
3939
+ repo: "mark1russell7/coeval",
3940
+ state: "published",
3941
+ words: [
3942
+ "parser",
3943
+ "evaluator",
3944
+ "dsl",
3945
+ "language",
3946
+ "ast",
3947
+ "scheduler",
3948
+ "incremental"
3949
+ ]
3950
+ },
3951
+ {
3952
+ area: "formulas",
3953
+ title: "Formulas over records",
3954
+ covers: "typed spreadsheet formulas evaluated at each record, tree node or grid cell; domains for vectors, colors, angles and numbers",
3955
+ packages: [
3956
+ "@mark1russell7/vex",
3957
+ "@mark1russell7/vex-domains",
3958
+ "@mark1russell7/vex-compiler"
3959
+ ],
3960
+ repo: "mark1russell7/vex",
3961
+ state: "published",
3962
+ words: [
3963
+ "formula",
3964
+ "spreadsheet",
3965
+ "roll-up",
3966
+ "aggregate",
3967
+ "per record",
3968
+ "grid"
3969
+ ]
3970
+ },
3971
+ {
3972
+ area: "reactive-ui",
3973
+ title: "Reactive expressions and rendering by type",
3974
+ covers: "the reactive node store and expressions of render, its viewer; splay renders any data with a viewer for each type",
3975
+ packages: [
3976
+ "@mark1russell7/render-dsl",
3977
+ "@mark1russell7/render-node",
3978
+ "@mark1russell7/splay"
3979
+ ],
3980
+ repo: "mark1russell7/render",
3981
+ state: "published",
3982
+ words: [
3983
+ "reactive",
3984
+ "signal",
3985
+ "subscription",
3986
+ "viewer",
3987
+ "render",
3988
+ "react"
3989
+ ],
3990
+ note: "@mark1russell7/splay is in mark1russell7/splay."
3991
+ },
3992
+ {
3993
+ area: "browser-monitoring",
3994
+ title: "Browser monitoring and context",
3995
+ covers: "main-thread lag, long tasks, Web Vitals, the page lifecycle, OpenTelemetry for the frontend, async context in browsers",
3996
+ packages: [
3997
+ "@mark1russell7/lag",
3998
+ "@mark1russell7/lag-hud",
3999
+ "page-lifecycle-tracker",
4000
+ "@mark1russell7/otel-ts",
4001
+ "async-browser-context"
4002
+ ],
4003
+ repo: "mark1russell7/lag",
4004
+ state: "published",
4005
+ words: [
4006
+ "telemetry",
4007
+ "web vitals",
4008
+ "inp",
4009
+ "long task",
4010
+ "visibility",
4011
+ "opentelemetry",
4012
+ "async context"
4013
+ ]
4014
+ },
4015
+ {
4016
+ area: "repo-structure",
4017
+ title: "Repository structure, CI and conventions",
4018
+ covers: "new repositories and packages, the CUE presets, shared CI workflows, the API report, import boundaries, the conventions check, the release and status pages",
4019
+ packages: [
4020
+ "@mark1russell7/conventions",
4021
+ "@mark1russell7/template-cli",
4022
+ "@mark1russell7/cue",
4023
+ "@mark1russell7/api-report",
4024
+ "@mark1russell7/boundaries",
4025
+ "@mark1russell7/site-pages"
4026
+ ],
4027
+ repo: "mark1russell7/template",
4028
+ state: "published",
4029
+ words: [
4030
+ "template",
4031
+ "ci",
4032
+ "workflow",
4033
+ "tsconfig",
4034
+ "package.json",
4035
+ "lint",
4036
+ "site",
4037
+ "pages"
4038
+ ]
4039
+ },
4040
+ {
4041
+ area: "prose",
4042
+ title: "Prose rules",
4043
+ covers: "the ASD-STE100 writing rules for Markdown and doc comments",
4044
+ packages: ["@mark1russell7/ste-lint"],
4045
+ repo: "mark1russell7/ste-lint",
4046
+ state: "published",
4047
+ words: [
4048
+ "docs",
4049
+ "readme",
4050
+ "writing",
4051
+ "ste"
4052
+ ]
4053
+ },
4054
+ {
4055
+ area: "machine-resources",
4056
+ title: "Memory and jobs on one computer",
4057
+ covers: "leases of memory and processors for jobs, queues of heavy jobs, alerts",
4058
+ packages: [],
4059
+ repo: "mark1russell7/headroom",
4060
+ state: "unpublished",
4061
+ words: [
4062
+ "memory",
4063
+ "lease",
4064
+ "job",
4065
+ "queue",
4066
+ "load"
4067
+ ]
4068
+ },
4069
+ {
4070
+ area: "releases",
4071
+ title: "Release order of the packages",
4072
+ covers: "the npm release and update plan in dependency order, provenance checks",
4073
+ packages: [],
4074
+ repo: "mark1russell7/release-train",
4075
+ state: "unpublished",
4076
+ words: [
4077
+ "release",
4078
+ "version",
4079
+ "semver",
4080
+ "provenance",
4081
+ "update"
4082
+ ]
4083
+ },
4084
+ {
4085
+ area: "duplication",
4086
+ title: "The duplication atlas",
4087
+ covers: "function shapes, clone classes, shared names and packages by purpose over all public repositories",
4088
+ packages: [],
4089
+ repo: "mark1russell7/codeatlas",
4090
+ state: "unpublished",
4091
+ words: [
4092
+ "duplicate",
4093
+ "clone",
4094
+ "copy"
4095
+ ]
4096
+ },
4097
+ {
4098
+ area: "web-crawling",
4099
+ title: "Web crawling",
4100
+ covers: "polite fetches with robots.txt and one request per site, a store of fetched pages",
4101
+ packages: ["polite-crawler", "polite-crawler-mcp"],
4102
+ repo: "mark1russell7/crawler",
4103
+ state: "published",
4104
+ words: [
4105
+ "crawl",
4106
+ "scrape",
4107
+ "robots",
4108
+ "fetch page"
4109
+ ]
4110
+ }
4111
+ ];
4112
+ /** A file of more homes, for example the private repositories, in the shape `{ "homes": Home[] }`. */
4113
+ function readOverlay(file) {
4114
+ const data = JSON.parse(readFileSync(file, "utf8"));
4115
+ if (!Array.isArray(data.homes)) throw new Error(`${file}: the field "homes" must be an array`);
4116
+ for (const home of data.homes) if (typeof home.area !== "string" || typeof home.title !== "string" || typeof home.repo !== "string") throw new Error(`${file}: each home needs area, title and repo`);
4117
+ return data.homes;
4118
+ }
4119
+ /** This function merges the homes. A home of `extra` with the area of a home of `base` takes its place. */
4120
+ function mergeHomes(base, extra) {
4121
+ const areas = new Set(extra.map((home) => home.area));
4122
+ return [...base.filter((home) => !areas.has(home.area)), ...extra];
4123
+ }
4124
+ /** This function gives the homes that match each word of `query`, best match first. */
4125
+ function findHomes(query, homes = HOMES) {
4126
+ const terms = query.toLowerCase().split(/\s+/).filter((term) => term.length > 0);
4127
+ if (terms.length === 0) return homes;
4128
+ const score = (home) => {
4129
+ const strong = [
4130
+ home.area,
4131
+ home.title,
4132
+ ...home.packages,
4133
+ ...home.words
4134
+ ].join(" ").toLowerCase();
4135
+ const weak = `${home.covers} ${home.note ?? ""}`.toLowerCase();
4136
+ return terms.reduce((sum, term) => sum + (strong.includes(term) ? 2 : weak.includes(term) ? 1 : 0), 0);
4137
+ };
4138
+ return homes.map((home, index) => ({
4139
+ home,
4140
+ index,
4141
+ score: score(home)
4142
+ })).filter((row) => row.score > 0).sort((a, b) => b.score - a.score || a.index - b.index).map((row) => row.home);
4143
+ }
4144
+ const STATE_TEXT = {
4145
+ published: "",
4146
+ unpublished: " (not on npm)",
4147
+ planned: " (planned)",
4148
+ none: " (no home)"
4149
+ };
4150
+ /** This function writes the map as a Markdown table, with the rule first. */
4151
+ function mapMarkdown(homes = HOMES) {
4152
+ const cell = (text) => text.replaceAll("|", "\\|");
4153
+ const rows = homes.map((home) => {
4154
+ const where = home.packages.length > 0 ? home.packages.map((name) => `\`${name}\``).join(", ") : `\`${home.repo}\``;
4155
+ const covers = home.note === void 0 ? home.covers : `${home.covers}. ${home.note}`;
4156
+ return `| ${cell(home.title)} | ${where}${STATE_TEXT[home.state]} | ${cell(covers)} |`;
4157
+ });
4158
+ return [
4159
+ MAP_RULE,
4160
+ "",
4161
+ "| Area | Home | Covers |",
4162
+ "| --- | --- | --- |",
4163
+ ...rows,
4164
+ ""
4165
+ ].join("\n");
4166
+ }
4167
+ /** This function writes the homes as plain text for a terminal. */
4168
+ function mapText(homes) {
4169
+ if (homes.length === 0) return "No area matches. Ask the strategist for a home before you write the code.\n";
4170
+ return homes.map((home) => {
4171
+ const where = home.packages.length > 0 ? home.packages.join(", ") : home.repo;
4172
+ const lines = [
4173
+ `${home.title} (${home.area}): ${where}${STATE_TEXT[home.state]}`,
4174
+ ` covers: ${home.covers}`,
4175
+ ` repo: ${home.repo}`
4176
+ ];
4177
+ if (home.note !== void 0) lines.push(` note: ${home.note}`);
4178
+ return lines.join("\n");
4179
+ }).join("\n\n").concat("\n");
4180
+ }
3559
4181
  // src/run.ts
3560
4182
  /**
3561
4183
  * The commands `check`, `fix` and `--list` of the bin `conventions`, as functions. `runChecks` starts the
@@ -3659,7 +4281,13 @@ function runChecks(options) {
3659
4281
  });
3660
4282
  continue;
3661
4283
  }
3662
- const breaks = outcome.filter((item) => !matchesAny(item.file, ruleConfig.ignore));
4284
+ const added = ruleConfig.ignore.length > 0 ? addedFiles(context) : void 0;
4285
+ const breaks = [];
4286
+ for (const item of outcome) if (!matchesAny(item.file, ruleConfig.ignore)) breaks.push(item);
4287
+ else if (added?.has(item.file) === true) breaks.push({
4288
+ ...item,
4289
+ message: `${item.message} The change adds this file, so \`ignore\` does not cover it.`
4290
+ });
3663
4291
  const ignored = outcome.length - breaks.length;
3664
4292
  const note = ruleConfig.reason === void 0 ? {} : { note: ruleConfig.reason };
3665
4293
  results.push({
@@ -3807,10 +4435,13 @@ function listRules(config, rules = RULES) {
3807
4435
  const USAGE = `Usage: conventions check [options]
3808
4436
  conventions fix [options]
3809
4437
  conventions --list
4438
+ conventions map [words] [--markdown | --json] [--overlay <file>]
3810
4439
 
3811
4440
  check Start each rule. Exit code 1 when a rule has a break.
3812
4441
  fix Write the fixes of the breaks that have one, and check again. Exit code 1 when a break stays.
3813
4442
  --list Show each rule: why, fix, options, state and the audit rows that it comes from.
4443
+ map Show the home package of each area of code, or of the areas that match the words.
4444
+ --markdown writes the table with the rule, and --overlay adds the homes of a JSON file.
3814
4445
 
3815
4446
  --root <folder> The root of the repository. The default is the current folder.
3816
4447
  --rule <id> Only this rule. Use it again for more rules.
@@ -3829,6 +4460,7 @@ with a reason, and sets the options of a rule with a reason:
3829
4460
  var UsageError = class extends Error {};
3830
4461
  /** This function starts the bin with the arguments `args`, and gives its exit code. */
3831
4462
  function runCli(args, io) {
4463
+ if (args[0] === "map") return runMap(args.slice(1), io);
3832
4464
  let check = false;
3833
4465
  let fix = false;
3834
4466
  let list = false;
@@ -3908,6 +4540,38 @@ function runCli(args, io) {
3908
4540
  if (summary) appendFileSync(summary, summaryMarkdown(result));
3909
4541
  return result.failed ? 1 : 0;
3910
4542
  }
3911
- export { hasFile as $, roadmapParses as A, REAL_COMPARE as B, isSourcePath as C, runnerBudget as D, repositoryOfRemote as E, pinnedGitDeps as F, gateTrigger as G, mainCheck as H, DEFAULT_ALLOWED as I, STRICT_OPTIONS as J, prPathFilters as K, HOME_PATTERNS as L, releaseFiles as M, isGitSpecifier as N, scheduleMinute as O, isPinned as P, codePackages as Q, noLocalPaths as R, tsconfigTest as S, sourceMain as T, ACTIONS_COMMIT as U, hasImportMetaMain as V, convertGate as W, DEPENDENCY_FIELDS as X, cuePreset as Y, cleanPath as Z, configsOfScript as _, listRules as a, readJsonc as at, testsRequired as b, runCli as c, specifiersOf as ct, RULES as d, packageFolders as dt, inFolder as et, workspaceProtocol as f, workspaceGlobs as ft, typedScripts as g, trustPolicy as h, formatResult as i, parseJsonc as it, requiredScripts as j, roadmapOfLine as k, runFix as l, globFolders as lt, TRAIN_SCOPES as m, parseConfig as mt, annotations as n, lineOf as nt, readConfig as o, replaceLine as ot, IGNORE_AFTER as p, defaultOptions as pt, summaryName as q, createContext as r, matchesAny as rt, runChecks as s, runGit as st, USAGE as t, keyLine as tt, summaryMarkdown as u, globToRegExp as ut, scriptsOf as v, pathsOf as w, hasTests as x, typedFiles as y, noBuildOutput as z };
4543
+ /** The command `map`: the home of each area, or of the areas that match the words. */
4544
+ function runMap(args, io) {
4545
+ let format = "text";
4546
+ let homes = HOMES;
4547
+ const words = [];
4548
+ for (let index = 0; index < args.length; index++) {
4549
+ const arg = args[index] ?? "";
4550
+ if (arg === "--markdown") format = "markdown";
4551
+ else if (arg === "--json") format = "json";
4552
+ else if (arg === "--overlay") {
4553
+ const file = args[++index];
4554
+ if (file === void 0) {
4555
+ io.stderr(`conventions: The option --overlay needs a value.\n\n${USAGE}`);
4556
+ return 2;
4557
+ }
4558
+ try {
4559
+ homes = mergeHomes(homes, readOverlay(resolve(io.cwd, file)));
4560
+ } catch (error) {
4561
+ io.stderr(`conventions: ${error instanceof Error ? error.message : String(error)}\n`);
4562
+ return 1;
4563
+ }
4564
+ } else if (arg.startsWith("-")) {
4565
+ io.stderr(`conventions: An unknown argument: ${arg}\n\n${USAGE}`);
4566
+ return 2;
4567
+ } else words.push(arg);
4568
+ }
4569
+ const found = findHomes(words.join(" "), homes);
4570
+ if (format === "json") io.stdout(`${JSON.stringify(found, null, 2)}\n`);
4571
+ else if (format === "markdown") io.stdout(mapMarkdown(found));
4572
+ else io.stdout(mapText(found));
4573
+ return 0;
4574
+ }
4575
+ export { prPathFilters as $, isSourcePath as A, isGitSpecifier as B, typedScripts as C, testsRequired as D, typedFiles as E, scheduleMinute as F, noLocalPaths as G, pinnedGitDeps as H, roadmapOfLine as I, hasImportMetaMain as J, noBuildOutput as K, roadmapParses as L, sourceMain as M, repositoryOfRemote as N, hasTests as O, runnerBudget as P, gateTrigger as Q, requiredScripts as R, trustPolicy as S, scriptsOf as T, DEFAULT_ALLOWED as U, isPinned as V, HOME_PATTERNS as W, ACTIONS_COMMIT as X, mainCheck as Y, convertGate as Z, readOverlay as _, globToRegExp as _t, listRules as a, codePackages as at, IGNORE_AFTER as b, defaultOptions as bt, runCli as c, keyLine as ct, HOMES as d, parseJsonc as dt, summaryName as et, MAP_RULE as f, readJsonc as ft, mergeHomes as g, globFolders as gt, mapText as h, specifiersOf as ht, formatResult as i, cleanPath as it, pathsOf as j, tsconfigTest as k, runFix as l, lineOf as lt, mapMarkdown as m, runGit as mt, annotations as n, cuePreset as nt, readConfig as o, hasFile as ot, findHomes as p, replaceLine as pt, REAL_COMPARE as q, createContext as r, DEPENDENCY_FIELDS as rt, runChecks as s, inFolder as st, USAGE as t, STRICT_OPTIONS as tt, summaryMarkdown as u, matchesAny as ut, RULES as v, packageFolders as vt, configsOfScript as w, TRAIN_SCOPES as x, parseConfig as xt, workspaceProtocol as y, workspaceGlobs as yt, releaseFiles as z };
3912
4576
 
3913
- //# sourceMappingURL=run-DKVHmESw.js.map
4577
+ //# sourceMappingURL=run-BxPv_FTo.js.map