rungate 0.4.0 → 0.5.0
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.
- package/config/behavioral-sc-map.json +170 -0
- package/config/brief-policies.json +28 -0
- package/config/ceremony-profiles.json +207 -0
- package/config/check-registry.json +114 -0
- package/config/matcher-registry.json +142 -0
- package/config/prove-evidence.schema.json +65 -0
- package/config/spec-policies.json +36 -0
- package/config/universal-rules.yaml +15 -0
- package/config/workflow-schema.json +279 -0
- package/lib/ac-quality.ts +119 -0
- package/lib/cli-commands.ts +7 -1
- package/lib/config-loader.ts +129 -5
- package/lib/conformity.ts +1122 -31
- package/lib/context-docs.ts +182 -0
- package/lib/create-brief.ts +22 -17
- package/lib/create-sc.ts +35 -8
- package/lib/doc-scan-targets.ts +435 -0
- package/lib/gate-check-audit.ts +9 -9
- package/lib/github.ts +195 -0
- package/lib/js-top-level-code.ts +27 -2
- package/lib/organize.ts +129 -40
- package/lib/package-closure.ts +387 -0
- package/lib/project-aliases.ts +100 -0
- package/lib/release-preflight.ts +352 -48
- package/lib/rungate-schema.ts +23 -1
- package/lib/sc-cover.ts +92 -1
- package/lib/sc-ids.ts +151 -0
- package/lib/scaffold/defaults.ts +40 -0
- package/lib/scaffold/managed-workflow.ts +125 -27
- package/lib/scaffold/owned-files.ts +6 -0
- package/lib/scaffold/profiles.ts +94 -0
- package/lib/scaffold/rehearsal.ts +355 -0
- package/lib/scaffold/steps.ts +787 -105
- package/lib/scaffold/write-steps.ts +208 -0
- package/lib/scratch-cleanup.ts +198 -0
- package/lib/scratch-roots.ts +94 -0
- package/lib/source-anchor.ts +144 -0
- package/lib/success-doc.ts +779 -0
- package/lib/suite-run-reading.ts +194 -0
- package/lib/test-census.ts +199 -0
- package/lib/trajectory.ts +377 -0
- package/lib/validators/spec-validators.ts +52 -35
- package/lib/workflow-security.ts +152 -7
- package/lib/workflow-test-harness.ts +349 -0
- package/lib/worktree-cleanup.ts +123 -7
- package/lib/worktree-repo.ts +165 -0
- package/package.json +10 -1
- package/scripts/audit-specs.ts +134 -37
- package/scripts/audit-transcript.ts +259 -0
- package/scripts/create-sc.ts +15 -1
- package/scripts/create-success.ts +162 -0
- package/scripts/detect-sc-drift.ts +200 -0
- package/scripts/extract-constraints.ts +16 -36
- package/scripts/scaffold-project.ts +51 -137
- package/scripts/split-spec.ts +315 -0
- package/scripts/sync-sc-status.ts +751 -0
- package/specs/SPEC-TEMPLATE.md +200 -0
- package/templates/SUCCESS-TEMPLATE.md +72 -0
- package/templates/agent-briefs/_shared.md +9 -0
- package/templates/agent-briefs/aditi.md +46 -0
- package/templates/agent-briefs/discovery.md +37 -0
- package/templates/agent-briefs/marcus.md +39 -0
- package/templates/agent-briefs/quinn.md +67 -0
- package/templates/agent-briefs/rook.md +40 -0
- package/templates/agent-briefs/serena.md +39 -0
package/lib/js-top-level-code.ts
CHANGED
|
@@ -35,7 +35,26 @@ function regexCanFollow(prev: string): boolean {
|
|
|
35
35
|
return !/[A-Za-z0-9_$)\]]/.test(prev);
|
|
36
36
|
}
|
|
37
37
|
|
|
38
|
-
|
|
38
|
+
/**
|
|
39
|
+
* `keepStringContents` leaves quoted string bodies intact while still blanking
|
|
40
|
+
* comments, regex literals and template text.
|
|
41
|
+
*
|
|
42
|
+
* Added for #484, which needs the opposite half of what every other caller
|
|
43
|
+
* wants: the path segments in `join(__dirname, "..", "config", "x.json")` are
|
|
44
|
+
* the payload, and the reason it needs this tokenizer at all is that the same
|
|
45
|
+
* expression written in a DOC COMMENT must not be read as a call. The first
|
|
46
|
+
* draft of that check scanned raw source and reported its own module docstring
|
|
47
|
+
* as a violation — #454 is the same mistake in CONFIG-1, two weeks earlier.
|
|
48
|
+
*
|
|
49
|
+
* It is an option on this function rather than a second stripper in that
|
|
50
|
+
* module on purpose. Two functions that each decide what a comment is are two
|
|
51
|
+
* deciders, and the one that is wrong is invisible — see
|
|
52
|
+
* `.claude/rules/checks-must-be-able-to-fail.md`.
|
|
53
|
+
*/
|
|
54
|
+
export function stripStringsAndComments(
|
|
55
|
+
src: string,
|
|
56
|
+
{ keepStringContents = false }: { keepStringContents?: boolean } = {},
|
|
57
|
+
): string {
|
|
39
58
|
let out = "";
|
|
40
59
|
let i = 0;
|
|
41
60
|
// Stack of brace depths, one entry per template literal currently open. An
|
|
@@ -100,13 +119,19 @@ export function stripStringsAndComments(src: string): string {
|
|
|
100
119
|
i++;
|
|
101
120
|
while (i < src.length) {
|
|
102
121
|
if (src[i] === "\\") {
|
|
122
|
+
// Carry the escape through verbatim under `keepStringContents`.
|
|
123
|
+
// Dropping both characters turned `"a\"b"` into `ab`, which is not
|
|
124
|
+
// a shorter version of the segment — it is a DIFFERENT path, and a
|
|
125
|
+
// caller resolving it would report a file the code never reads.
|
|
126
|
+
// Silently wrong beats loudly wrong only in the wrong direction.
|
|
127
|
+
if (keepStringContents) out += src.slice(i, i + 2);
|
|
103
128
|
i += 2;
|
|
104
129
|
continue;
|
|
105
130
|
}
|
|
106
131
|
if (src[i] === quote) break;
|
|
107
132
|
// Unterminated strings must not swallow the rest of the file.
|
|
108
133
|
if (src[i] === "\n") break;
|
|
109
|
-
out += src[i]
|
|
134
|
+
out += keepStringContents ? src[i] : "";
|
|
110
135
|
i++;
|
|
111
136
|
}
|
|
112
137
|
if (src[i] === quote) {
|
package/lib/organize.ts
CHANGED
|
@@ -21,6 +21,7 @@ import {
|
|
|
21
21
|
} from "fs";
|
|
22
22
|
import { join, relative, dirname, basename } from "path";
|
|
23
23
|
import { loadComplianceConfig, type OrganizeExternalSource } from "./config-loader.js";
|
|
24
|
+
import { matchesAnyAlias, projectAliases } from "./project-aliases.js";
|
|
24
25
|
|
|
25
26
|
// ── Types ────────────────────────────────────────────────────────
|
|
26
27
|
|
|
@@ -64,6 +65,27 @@ export interface OrganizeOptions {
|
|
|
64
65
|
harnessRoot?: string;
|
|
65
66
|
}
|
|
66
67
|
|
|
68
|
+
/**
|
|
69
|
+
* What a scan covered, and what it could not (#442).
|
|
70
|
+
*
|
|
71
|
+
* `scanExternalSources` had three fail-opens in one loop: a declared path
|
|
72
|
+
* that is not on disk was `continue`d, an unreadable file was `catch {}`ed
|
|
73
|
+
* into a non-match, and the whole directory walk sat inside another bare
|
|
74
|
+
* `catch`. A user who declares where their documents live and is told
|
|
75
|
+
* nothing when that place is not there has been given `0`, `{}` and `SKIP`
|
|
76
|
+
* — which `.claude/rules/config-access.md` names as indistinguishable from
|
|
77
|
+
* success. `UNMEASURED` is not.
|
|
78
|
+
*/
|
|
79
|
+
export interface OrganizeReport {
|
|
80
|
+
proposals: OrganizeProposal[];
|
|
81
|
+
/** Declared external paths that are not on disk. Named, not skipped. */
|
|
82
|
+
unmeasured: string[];
|
|
83
|
+
/** Paths that exist and could not be read. A non-match is not the answer. */
|
|
84
|
+
unreadable: string[];
|
|
85
|
+
/** The names matching was actually done against, so a miss is diagnosable. */
|
|
86
|
+
aliases: string[];
|
|
87
|
+
}
|
|
88
|
+
|
|
67
89
|
// ── Well-known root files to skip ────────────────────────────────
|
|
68
90
|
|
|
69
91
|
const WELL_KNOWN_ROOT_FILES = new Set([
|
|
@@ -288,7 +310,14 @@ export function classifyDocument(
|
|
|
288
310
|
|
|
289
311
|
// ── Main organize function ───────────────────────────────────────
|
|
290
312
|
|
|
291
|
-
|
|
313
|
+
/**
|
|
314
|
+
* The full result: what was proposed, and what could not be looked at.
|
|
315
|
+
*
|
|
316
|
+
* `organizeProject` below is a view onto this, not a second implementation —
|
|
317
|
+
* eight call sites want only the proposals and changing them all would have
|
|
318
|
+
* bought nothing. One decider, one convenience accessor.
|
|
319
|
+
*/
|
|
320
|
+
export function organizeProjectReport(root: string, options: OrganizeOptions = {}): OrganizeReport {
|
|
292
321
|
const complianceConfig = options.harnessRoot
|
|
293
322
|
? loadComplianceConfig(options.harnessRoot)
|
|
294
323
|
: null;
|
|
@@ -316,71 +345,131 @@ export function organizeProject(root: string, options: OrganizeOptions = {}): Or
|
|
|
316
345
|
});
|
|
317
346
|
}
|
|
318
347
|
|
|
348
|
+
const aliases = projectAliases(root, organizeConfig?.aliases ?? []);
|
|
349
|
+
const report: OrganizeReport = { proposals, unmeasured: [], unreadable: [], aliases };
|
|
350
|
+
|
|
319
351
|
// Scan external sources from config
|
|
320
352
|
if (organizeConfig?.externalSources) {
|
|
321
|
-
|
|
322
|
-
proposals.push(...externalProposals);
|
|
353
|
+
proposals.push(...scanExternalSources(root, organizeConfig.externalSources, aliases, report));
|
|
323
354
|
}
|
|
324
355
|
|
|
325
356
|
if (options.apply && !options.dryRun) {
|
|
326
357
|
executeProposals(root, proposals);
|
|
327
358
|
}
|
|
328
359
|
|
|
329
|
-
return
|
|
360
|
+
return report;
|
|
361
|
+
}
|
|
362
|
+
|
|
363
|
+
export function organizeProject(root: string, options: OrganizeOptions = {}): OrganizeProposal[] {
|
|
364
|
+
return organizeProjectReport(root, options).proposals;
|
|
330
365
|
}
|
|
331
366
|
|
|
332
367
|
// ── External source scanning ────────────────────────────────────
|
|
333
368
|
|
|
334
|
-
function scanExternalSources(
|
|
369
|
+
function scanExternalSources(
|
|
370
|
+
projectRoot: string,
|
|
371
|
+
sources: OrganizeExternalSource[],
|
|
372
|
+
aliases: string[],
|
|
373
|
+
report: { unmeasured: string[]; unreadable: string[] },
|
|
374
|
+
): OrganizeProposal[] {
|
|
335
375
|
const proposals: OrganizeProposal[] = [];
|
|
336
|
-
const projectName = basename(projectRoot).toLowerCase();
|
|
337
376
|
|
|
338
377
|
for (const source of sources) {
|
|
339
|
-
const expandedPath = source.path
|
|
340
|
-
if (!existsSync(expandedPath))
|
|
378
|
+
const expandedPath = expandHome(source.path);
|
|
379
|
+
if (!existsSync(expandedPath)) {
|
|
380
|
+
// UNMEASURED, not skipped. The user said their documents live here.
|
|
381
|
+
report.unmeasured.push(source.path);
|
|
382
|
+
continue;
|
|
383
|
+
}
|
|
341
384
|
if (source.target === null) continue;
|
|
342
385
|
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
}
|
|
386
|
+
let stat;
|
|
387
|
+
try {
|
|
388
|
+
stat = lstatSync(expandedPath);
|
|
389
|
+
} catch {
|
|
390
|
+
report.unreadable.push(source.path);
|
|
391
|
+
continue;
|
|
392
|
+
}
|
|
393
|
+
if (!stat.isDirectory()) continue;
|
|
394
|
+
|
|
395
|
+
let entries: string[];
|
|
396
|
+
try {
|
|
397
|
+
entries = readdirSync(expandedPath);
|
|
398
|
+
} catch {
|
|
399
|
+
// Was a bare `catch {}` around the whole walk. A declared source the
|
|
400
|
+
// process cannot list is the single most important thing to say.
|
|
401
|
+
report.unreadable.push(source.path);
|
|
402
|
+
continue;
|
|
403
|
+
}
|
|
362
404
|
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
405
|
+
for (const entry of entries) {
|
|
406
|
+
const entryPath = join(expandedPath, entry);
|
|
407
|
+
let isDir: boolean;
|
|
408
|
+
try {
|
|
409
|
+
isDir = lstatSync(entryPath).isDirectory();
|
|
410
|
+
} catch {
|
|
411
|
+
report.unreadable.push(entryPath);
|
|
412
|
+
continue;
|
|
413
|
+
}
|
|
414
|
+
if (!isDir && !entry.endsWith(".md")) continue;
|
|
415
|
+
|
|
416
|
+
let matches = false;
|
|
417
|
+
if (source.matchBy === "project-name") {
|
|
418
|
+
matches = matchesAnyAlias(entry, aliases);
|
|
419
|
+
if (!matches && isDir) {
|
|
420
|
+
try {
|
|
421
|
+
matches = readdirSync(entryPath).some(f => matchesAnyAlias(f, aliases));
|
|
422
|
+
} catch {
|
|
423
|
+
report.unreadable.push(entryPath);
|
|
424
|
+
continue;
|
|
375
425
|
}
|
|
376
426
|
}
|
|
377
|
-
}
|
|
427
|
+
} else if (source.matchBy === "content-reference") {
|
|
428
|
+
if (!entry.endsWith(".md")) continue;
|
|
429
|
+
let content: string;
|
|
430
|
+
try {
|
|
431
|
+
content = readFileSync(entryPath, "utf-8");
|
|
432
|
+
} catch {
|
|
433
|
+
// Was `catch {}`, which made unreadable and not-a-match the same
|
|
434
|
+
// answer. They are opposite answers: one is "no", the other is
|
|
435
|
+
// "I could not look".
|
|
436
|
+
report.unreadable.push(entryPath);
|
|
437
|
+
continue;
|
|
438
|
+
}
|
|
439
|
+
matches = matchesAnyAlias(content, aliases);
|
|
440
|
+
}
|
|
441
|
+
|
|
442
|
+
if (!matches) continue;
|
|
443
|
+
|
|
444
|
+
const targetPath = join(source.target, entry);
|
|
445
|
+
if (existsSync(join(projectRoot, targetPath))) continue;
|
|
446
|
+
|
|
447
|
+
proposals.push({
|
|
448
|
+
source: entryPath,
|
|
449
|
+
target: targetPath,
|
|
450
|
+
classification: source.type,
|
|
451
|
+
reasoning: `external ${source.type} matched by ${source.matchBy} in ${source.path}`,
|
|
452
|
+
confidence: 0.7,
|
|
453
|
+
});
|
|
378
454
|
}
|
|
379
455
|
}
|
|
380
456
|
|
|
381
457
|
return proposals;
|
|
382
458
|
}
|
|
383
459
|
|
|
460
|
+
/**
|
|
461
|
+
* `~` expansion, anchored.
|
|
462
|
+
*
|
|
463
|
+
* `source.path.replace("~", HOME)` replaces the FIRST `~` anywhere in the
|
|
464
|
+
* string, so `/srv/backup~old/docs` became `/srv/backup<HOME>old/docs`. Only
|
|
465
|
+
* a leading `~` is a home reference.
|
|
466
|
+
*/
|
|
467
|
+
export function expandHome(path: string): string {
|
|
468
|
+
if (path !== "~" && !path.startsWith("~/")) return path;
|
|
469
|
+
const home = process.env.HOME || "";
|
|
470
|
+
return home ? home + path.slice(1) : path;
|
|
471
|
+
}
|
|
472
|
+
|
|
384
473
|
// ── Execute proposals (move files) ───────────────────────────────
|
|
385
474
|
|
|
386
475
|
function executeProposals(root: string, proposals: OrganizeProposal[]): void {
|
|
@@ -0,0 +1,387 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Package closure — does everything the tarball ships still resolve once it is
|
|
3
|
+
* the only thing on disk?
|
|
4
|
+
*
|
|
5
|
+
* `lib/` publishes whole. `scripts/` publishes by allowlist, one path at a
|
|
6
|
+
* time. An import that crosses from the first into the second is only sound
|
|
7
|
+
* while the allowlist happens to name its target, and nothing checked that.
|
|
8
|
+
* `lib/conformity.ts` imported `../scripts/split-spec` through two releases
|
|
9
|
+
* with the file left out, so every consumer of `rungate/lib/conformity` died
|
|
10
|
+
* on import while the repo stayed green — the suites resolve that path against
|
|
11
|
+
* the working tree, where it exists (#446).
|
|
12
|
+
*
|
|
13
|
+
* The check is static and offline: expand `files[]` into the set the tarball
|
|
14
|
+
* would carry, then walk the relative imports of every published source file
|
|
15
|
+
* and assert each target is in that set. One `catch` here would turn a
|
|
16
|
+
* malformed package.json into "no violations", so there is none.
|
|
17
|
+
*
|
|
18
|
+
* ## Imports were half of it (#484)
|
|
19
|
+
*
|
|
20
|
+
* The version of this module that shipped with #446 asked one question —
|
|
21
|
+
* *does every relative IMPORT resolve to a published file?* — and `0.4.1` went
|
|
22
|
+
* out with `SUCCESS.md` recording that the distribution had been verified. It
|
|
23
|
+
* had been verified for imports.
|
|
24
|
+
*
|
|
25
|
+
* `lib/conformity.ts:495` does not import its matcher registry. It builds a
|
|
26
|
+
* path and reads it:
|
|
27
|
+
*
|
|
28
|
+
* join(dirname(fileURLToPath(import.meta.url)), "..", "config", "matcher-registry.json")
|
|
29
|
+
*
|
|
30
|
+
* `config/` was not in `files[]`, so `resolveMatcher()` threw ENOENT for every
|
|
31
|
+
* consumer, and `bunx rungate create-sc --list` — a command the README
|
|
32
|
+
* documents — died the same way. Same defect as #446, different syntax, and
|
|
33
|
+
* the guard written for #446 was structurally incapable of seeing it: a
|
|
34
|
+
* detector narrower than what it detects, which is the shape
|
|
35
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` names third.
|
|
36
|
+
*
|
|
37
|
+
* What made it latent rather than loud is worth recording. An external
|
|
38
|
+
* consumer does not reach `resolveMatcher` until one of its success criteria
|
|
39
|
+
* MATCHES a registry pattern. Measured on `pov-plugin`: 21 pass, 0 fail, over
|
|
40
|
+
* a library that could not load its own registry, purely because all 40 of its
|
|
41
|
+
* SCs were unmatched. The reward for making its spec more testable would have
|
|
42
|
+
* been an ENOENT crash, and nothing connected those two events.
|
|
43
|
+
*
|
|
44
|
+
* So both syntaxes are asked the same question here, and `runtimeReads` is
|
|
45
|
+
* deliberately NOT a second copy of the import walker — the two find different
|
|
46
|
+
* things and both feed the one `packageClosureViolations` binding, so there is
|
|
47
|
+
* still exactly one decider to mutate.
|
|
48
|
+
*/
|
|
49
|
+
import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from "fs";
|
|
50
|
+
import { join, dirname, relative, resolve } from "path";
|
|
51
|
+
import { stripStringsAndComments } from "./js-top-level-code";
|
|
52
|
+
|
|
53
|
+
/** Extensions a bare specifier may acquire, in the order a resolver tries. */
|
|
54
|
+
const CANDIDATE_SUFFIXES = ["", ".ts", ".tsx", ".js", ".mjs", ".json", "/index.ts", "/index.js"];
|
|
55
|
+
|
|
56
|
+
const SOURCE_EXT = /\.(ts|tsx|mts|js|mjs)$/;
|
|
57
|
+
|
|
58
|
+
/** `files[]` entries are either a directory ("lib/") or one exact path. */
|
|
59
|
+
export function publishedFiles(root: string, patterns: string[]): Set<string> {
|
|
60
|
+
const out = new Set<string>();
|
|
61
|
+
|
|
62
|
+
function addDir(rel: string) {
|
|
63
|
+
const abs = join(root, rel);
|
|
64
|
+
if (!existsSync(abs)) return;
|
|
65
|
+
for (const entry of readdirSync(abs)) {
|
|
66
|
+
const childRel = `${rel}/${entry}`.replace(/\/+/g, "/");
|
|
67
|
+
const childAbs = join(root, childRel);
|
|
68
|
+
// `lstat`, not `stat`. A symlink inside a published directory points
|
|
69
|
+
// wherever it likes, and `relative()` cannot see that because the path
|
|
70
|
+
// STRING is still under the root — a `linked/` symlink enumerated
|
|
71
|
+
// `secret.txt` from a directory outside the package entirely. npm would
|
|
72
|
+
// follow it into the tarball too, so this is a packaging hazard either
|
|
73
|
+
// way and the honest answer is to refuse rather than to model it.
|
|
74
|
+
const st = lstatSync(childAbs);
|
|
75
|
+
if (st.isSymbolicLink()) {
|
|
76
|
+
throw new Error(`package.json files[] reaches a symlink at "${childRel}" — refusing to resolve it`);
|
|
77
|
+
}
|
|
78
|
+
if (st.isDirectory()) addDir(childRel);
|
|
79
|
+
else out.add(childRel);
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/** npm expands these; this checker does not, and must not pretend to. */
|
|
84
|
+
const GLOB_META = /[*?[\]{}!]/;
|
|
85
|
+
|
|
86
|
+
for (const pattern of patterns) {
|
|
87
|
+
// A glob is not a path, and treating it as one resolves to NOTHING:
|
|
88
|
+
// `files: ["scripts/*.ts"]` produced a published set containing only
|
|
89
|
+
// package.json, so the closure loop had almost nothing to walk and
|
|
90
|
+
// reported zero violations over a package it had not looked at. That is
|
|
91
|
+
// the same vacuous-scan failure CONFIG-1 refuses, reached through the
|
|
92
|
+
// manifest instead of through the file walk.
|
|
93
|
+
if (GLOB_META.test(pattern)) {
|
|
94
|
+
throw new Error(
|
|
95
|
+
`package.json files[] entry "${pattern}" is a glob, which this checker does not expand — ` +
|
|
96
|
+
`it would report a clean closure over files it never resolved`,
|
|
97
|
+
);
|
|
98
|
+
}
|
|
99
|
+
const clean = pattern.replace(/^\.\//, "").replace(/\/$/, "");
|
|
100
|
+
const abs = join(root, clean);
|
|
101
|
+
// A files[] entry that climbs out of the package is never legitimate, and
|
|
102
|
+
// this function walks directories recursively — so an unchecked `../..`
|
|
103
|
+
// would enumerate the filesystem above the project. Refuse rather than
|
|
104
|
+
// normalise: npm would not publish it either, and silently reading it as
|
|
105
|
+
// the directory it resolves to would hide a malformed manifest.
|
|
106
|
+
if (relative(root, abs).startsWith("..")) {
|
|
107
|
+
throw new Error(`package.json files[] entry "${pattern}" escapes the package root`);
|
|
108
|
+
}
|
|
109
|
+
if (!existsSync(abs)) continue;
|
|
110
|
+
// The same lstat the recursion does. A first draft checked only inside
|
|
111
|
+
// addDir, so `files: ["linked/"]` — the symlink named as the entry itself
|
|
112
|
+
// — walked straight past it and enumerated a directory outside the
|
|
113
|
+
// package. The guard has to sit on every path that becomes a published
|
|
114
|
+
// name, not only on the ones reached by recursion.
|
|
115
|
+
if (lstatSync(abs).isSymbolicLink()) {
|
|
116
|
+
throw new Error(`package.json files[] entry "${pattern}" is a symlink — refusing to resolve it`);
|
|
117
|
+
}
|
|
118
|
+
if (statSync(abs).isDirectory()) addDir(clean);
|
|
119
|
+
else out.add(clean);
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
// npm always includes these regardless of files[].
|
|
123
|
+
for (const always of ["package.json", "README.md", "LICENSE"]) {
|
|
124
|
+
if (existsSync(join(root, always))) out.add(always);
|
|
125
|
+
}
|
|
126
|
+
return out;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/** Relative specifiers only — bare ones are the dependency resolver's problem. */
|
|
130
|
+
export function relativeImports(source: string): string[] {
|
|
131
|
+
const found: string[] = [];
|
|
132
|
+
const patterns = [
|
|
133
|
+
/\bfrom\s+["'](\.[^"']+)["']/g,
|
|
134
|
+
/\bimport\s+["'](\.[^"']+)["']/g,
|
|
135
|
+
/\bimport\s*\(\s*["'](\.[^"']+)["']\s*\)/g,
|
|
136
|
+
/\brequire\s*\(\s*["'](\.[^"']+)["']\s*\)/g,
|
|
137
|
+
];
|
|
138
|
+
for (const pattern of patterns) {
|
|
139
|
+
let m: RegExpExecArray | null;
|
|
140
|
+
while ((m = pattern.exec(source)) !== null) found.push(m[1]);
|
|
141
|
+
}
|
|
142
|
+
return found;
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
/**
|
|
146
|
+
* A path a module builds from its OWN location and then reads at runtime.
|
|
147
|
+
*
|
|
148
|
+
* `up` is how many directories above the source file the path starts, and
|
|
149
|
+
* `segments` is what is appended. The two anchors below both mean "the
|
|
150
|
+
* directory this module is in", so they are 0; every `dirname()` wrapped
|
|
151
|
+
* around one, and every `".."` among the segments, adds a level.
|
|
152
|
+
*/
|
|
153
|
+
export interface RuntimeRead {
|
|
154
|
+
/** The expression as written, for the violation message. */
|
|
155
|
+
expression: string;
|
|
156
|
+
/** Directories above the source file's own directory. */
|
|
157
|
+
up: number;
|
|
158
|
+
/** Literal path segments below that, `..` already folded into `up`. */
|
|
159
|
+
segments: string[];
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/** Spellings of "the directory this module lives in". */
|
|
163
|
+
const MODULE_DIR_ANCHORS = [
|
|
164
|
+
/\bdirname\s*\(\s*fileURLToPath\s*\(\s*import\.meta\.url\s*\)\s*\)/,
|
|
165
|
+
/\bimport\.meta\.dir\b/,
|
|
166
|
+
/\b__dirname\b/,
|
|
167
|
+
];
|
|
168
|
+
|
|
169
|
+
/** Split a `join(...)` argument list on top-level commas. */
|
|
170
|
+
function splitArgs(argText: string): string[] {
|
|
171
|
+
const args: string[] = [];
|
|
172
|
+
let depth = 0;
|
|
173
|
+
let quote: string | null = null;
|
|
174
|
+
let current = "";
|
|
175
|
+
for (let i = 0; i < argText.length; i++) {
|
|
176
|
+
const c = argText[i];
|
|
177
|
+
if (quote) {
|
|
178
|
+
if (c === quote && argText[i - 1] !== "\\") quote = null;
|
|
179
|
+
current += c;
|
|
180
|
+
continue;
|
|
181
|
+
}
|
|
182
|
+
if (c === '"' || c === "'" || c === "`") { quote = c; current += c; continue; }
|
|
183
|
+
if (c === "(" || c === "[" || c === "{") depth++;
|
|
184
|
+
if (c === ")" || c === "]" || c === "}") depth--;
|
|
185
|
+
if (c === "," && depth === 0) { args.push(current.trim()); current = ""; continue; }
|
|
186
|
+
current += c;
|
|
187
|
+
}
|
|
188
|
+
if (current.trim()) args.push(current.trim());
|
|
189
|
+
return args;
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
/**
|
|
193
|
+
* A segment the scanner is willing to resolve.
|
|
194
|
+
*
|
|
195
|
+
* No backslash: an escaped character means the written text and the runtime
|
|
196
|
+
* string differ, and resolving the text would name a path the code does not
|
|
197
|
+
* read. Such a segment falls through to `unresolved`, where it is reported,
|
|
198
|
+
* rather than being turned into a plausible wrong answer.
|
|
199
|
+
*/
|
|
200
|
+
const STRING_LITERAL = /^["'`]([^"'`\\]*)["'`]$/;
|
|
201
|
+
|
|
202
|
+
/**
|
|
203
|
+
* Every `join(<this module's directory>, ...literals)` in a source file.
|
|
204
|
+
*
|
|
205
|
+
* Only fully-literal segment lists are returned. A `join` whose segments come
|
|
206
|
+
* from a variable cannot be resolved statically and is NOT silently dropped —
|
|
207
|
+
* `unresolvedModuleRelativeJoins` counts those separately so a new one is
|
|
208
|
+
* visible rather than absorbed, which is the fail-open this whole module
|
|
209
|
+
* exists to avoid.
|
|
210
|
+
*/
|
|
211
|
+
export function runtimeReads(source: string): RuntimeRead[] {
|
|
212
|
+
return scanModuleRelativeJoins(source).resolved;
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
/** Module-relative `join(...)` calls whose segments are not all literals. */
|
|
216
|
+
export function unresolvedModuleRelativeJoins(source: string): string[] {
|
|
217
|
+
return scanModuleRelativeJoins(source).unresolved;
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
function scanModuleRelativeJoins(raw: string): { resolved: RuntimeRead[]; unresolved: string[] } {
|
|
221
|
+
const resolved: RuntimeRead[] = [];
|
|
222
|
+
const unresolved: string[] = [];
|
|
223
|
+
|
|
224
|
+
// Comments out, string contents kept. The first draft of this scanner read
|
|
225
|
+
// raw source and reported THIS MODULE's own docstring — which quotes the
|
|
226
|
+
// `join(dirname(fileURLToPath(...)), "..", "config", ...)` expression to
|
|
227
|
+
// explain the bug — as a live violation. A detector that cannot tell a call
|
|
228
|
+
// from a sentence about a call is #454 again.
|
|
229
|
+
const source = stripStringsAndComments(raw, { keepStringContents: true });
|
|
230
|
+
|
|
231
|
+
for (let i = source.indexOf("join"); i !== -1; i = source.indexOf("join", i + 1)) {
|
|
232
|
+
// `join` must be the whole identifier, and an open paren must follow.
|
|
233
|
+
if (i > 0 && /[A-Za-z0-9_$.]/.test(source[i - 1])) continue;
|
|
234
|
+
let j = i + 4;
|
|
235
|
+
while (j < source.length && /\s/.test(source[j])) j++;
|
|
236
|
+
if (source[j] !== "(") continue;
|
|
237
|
+
|
|
238
|
+
// Walk to the matching close paren.
|
|
239
|
+
let depth = 0;
|
|
240
|
+
let k = j;
|
|
241
|
+
for (; k < source.length; k++) {
|
|
242
|
+
if (source[k] === "(") depth++;
|
|
243
|
+
else if (source[k] === ")") { depth--; if (depth === 0) break; }
|
|
244
|
+
}
|
|
245
|
+
if (depth !== 0) continue;
|
|
246
|
+
|
|
247
|
+
const argText = source.slice(j + 1, k);
|
|
248
|
+
const args = splitArgs(argText);
|
|
249
|
+
if (args.length < 2) continue;
|
|
250
|
+
|
|
251
|
+
const anchor = args[0];
|
|
252
|
+
if (!MODULE_DIR_ANCHORS.some(a => a.test(anchor))) continue;
|
|
253
|
+
|
|
254
|
+
// `dirname(fileURLToPath(import.meta.url))` IS the anchor, so remove it
|
|
255
|
+
// before counting the dirname() calls that genuinely climb.
|
|
256
|
+
const climbing = anchor.replace(MODULE_DIR_ANCHORS[0], "");
|
|
257
|
+
let up = (climbing.match(/\bdirname\s*\(/g) || []).length;
|
|
258
|
+
|
|
259
|
+
const expression = `join(${args.join(", ")})`;
|
|
260
|
+
const segments: string[] = [];
|
|
261
|
+
let literal = true;
|
|
262
|
+
for (const arg of args.slice(1)) {
|
|
263
|
+
const m = STRING_LITERAL.exec(arg);
|
|
264
|
+
if (!m) { literal = false; break; }
|
|
265
|
+
for (const part of m[1].split("/").filter(Boolean)) {
|
|
266
|
+
if (part === "..") { if (segments.length) segments.pop(); else up++; }
|
|
267
|
+
else if (part !== ".") segments.push(part);
|
|
268
|
+
}
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
// `join(import.meta.dir, "..")` with nothing below it is the "find the
|
|
272
|
+
// package root" idiom, not a read of a particular file. Eleven published
|
|
273
|
+
// modules use it and none of them is a closure question.
|
|
274
|
+
if (literal && segments.length > 0) resolved.push({ expression, up, segments });
|
|
275
|
+
else if (!literal) unresolved.push(expression);
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
return { resolved, unresolved };
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
/**
|
|
282
|
+
* The single binding. `test/package-closure.test.ts` builds a mutant of this
|
|
283
|
+
* module with the body short-circuited to `return []` and asserts the suite
|
|
284
|
+
* goes quiet over a package that is genuinely broken — which is the only thing
|
|
285
|
+
* separating this from a line in a report.
|
|
286
|
+
*/
|
|
287
|
+
export function packageClosureViolations(root: string, published: Set<string>): string[] {
|
|
288
|
+
const violations: string[] = [];
|
|
289
|
+
let scanned = 0;
|
|
290
|
+
|
|
291
|
+
for (const file of published) {
|
|
292
|
+
if (!SOURCE_EXT.test(file)) continue;
|
|
293
|
+
scanned++;
|
|
294
|
+
const source = readFileSync(join(root, file), "utf-8");
|
|
295
|
+
|
|
296
|
+
// A module-relative path the scanner could not resolve statically is
|
|
297
|
+
// UNMEASURED, and unmeasured is not clean. The first draft of this module
|
|
298
|
+
// exported `unresolvedModuleRelativeJoins`, tested it in isolation, and
|
|
299
|
+
// never called it from here — so its own docstring claimed these were
|
|
300
|
+
// "NOT silently dropped" while the only path that produces violations
|
|
301
|
+
// dropped them. Found by the push security review, in the same commit
|
|
302
|
+
// that adds a section about exactly this to
|
|
303
|
+
// `.claude/rules/checks-must-be-able-to-fail.md`.
|
|
304
|
+
//
|
|
305
|
+
// Enforced strictly because the live tree has zero: there is no migration
|
|
306
|
+
// window to ratchet through, so a new one fails immediately.
|
|
307
|
+
for (const expression of unresolvedModuleRelativeJoins(source)) {
|
|
308
|
+
violations.push(
|
|
309
|
+
`${file} builds ${expression} from its own directory and the segments are not all literal — ` +
|
|
310
|
+
`the scanner cannot say what it reads, so whether it ships is UNMEASURED`,
|
|
311
|
+
);
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
// `join` resolved by identifier. An aliased import would be invisible, so
|
|
315
|
+
// it is refused rather than missed — the blind spot is small, and the
|
|
316
|
+
// point is that entering it cannot be silent.
|
|
317
|
+
if (/\bimport\s*\{[^}]*\bjoin\s+as\s+\w/.test(source)) {
|
|
318
|
+
violations.push(
|
|
319
|
+
`${file} imports join under an alias, which this scanner resolves by name and would not see`,
|
|
320
|
+
);
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
// #484. A path built from the module's own location and read at runtime
|
|
324
|
+
// asks the same question an import does, so it is answered here and not
|
|
325
|
+
// in a second checker that could drift from this one.
|
|
326
|
+
for (const read of runtimeReads(source)) {
|
|
327
|
+
let dir = dirname(join(root, file));
|
|
328
|
+
for (let n = 0; n < read.up; n++) dir = dirname(dir);
|
|
329
|
+
const target = join(dir, ...read.segments);
|
|
330
|
+
const targetRel = relative(root, target);
|
|
331
|
+
|
|
332
|
+
// Outside the package entirely is not this check's business.
|
|
333
|
+
if (targetRel.startsWith("..")) continue;
|
|
334
|
+
if (!existsSync(target)) continue;
|
|
335
|
+
|
|
336
|
+
const isPublished = statSync(target).isDirectory()
|
|
337
|
+
? [...published].some(p => p === targetRel || p.startsWith(`${targetRel}/`))
|
|
338
|
+
: published.has(targetRel);
|
|
339
|
+
|
|
340
|
+
if (!isPublished) {
|
|
341
|
+
violations.push(
|
|
342
|
+
`${file} reads ${read.expression} at runtime -> ${targetRel}, which files[] does not publish`,
|
|
343
|
+
);
|
|
344
|
+
}
|
|
345
|
+
}
|
|
346
|
+
|
|
347
|
+
for (const specifier of relativeImports(source)) {
|
|
348
|
+
const target = resolve(dirname(join(root, file)), specifier);
|
|
349
|
+
const targetRel = relative(root, target);
|
|
350
|
+
|
|
351
|
+
// Resolvable against the working tree but absent from the tarball is
|
|
352
|
+
// the whole defect — a path that does not exist at all is a different
|
|
353
|
+
// bug, and typecheck already owns it.
|
|
354
|
+
const existsOnDisk = CANDIDATE_SUFFIXES.some(s => existsSync(target + s));
|
|
355
|
+
if (!existsOnDisk) continue;
|
|
356
|
+
|
|
357
|
+
const isPublished = CANDIDATE_SUFFIXES.some(s => published.has(`${targetRel}${s}`.replace(/\/+/g, "/")));
|
|
358
|
+
if (!isPublished) {
|
|
359
|
+
violations.push(`${file} imports "${specifier}" -> ${targetRel}, which files[] does not publish`);
|
|
360
|
+
}
|
|
361
|
+
}
|
|
362
|
+
}
|
|
363
|
+
|
|
364
|
+
// A closure check that walked no source reports a closed package and cannot
|
|
365
|
+
// be told from one. Every way of producing an empty set found so far — a
|
|
366
|
+
// glob entry, a files[] naming only non-source, a wrong root — throws or
|
|
367
|
+
// refuses somewhere above; this is the backstop for the next one, because
|
|
368
|
+
// the list of ways is not knowable in advance. ADR-002 D4, same argument.
|
|
369
|
+
if (scanned === 0) {
|
|
370
|
+
return [
|
|
371
|
+
"package closure: NO published source files were scanned. A check that reads nothing " +
|
|
372
|
+
"reports nothing and cannot be told from a closed package — refusing rather than " +
|
|
373
|
+
"reporting clean.",
|
|
374
|
+
];
|
|
375
|
+
}
|
|
376
|
+
return violations.sort();
|
|
377
|
+
}
|
|
378
|
+
|
|
379
|
+
export function readPackageFiles(root: string): string[] {
|
|
380
|
+
// Deliberately unguarded: a malformed package.json must throw, not read as
|
|
381
|
+
// a package with nothing in it.
|
|
382
|
+
const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf-8"));
|
|
383
|
+
if (!Array.isArray(pkg.files)) {
|
|
384
|
+
throw new Error("package.json has no files[] array — cannot determine what ships");
|
|
385
|
+
}
|
|
386
|
+
return pkg.files;
|
|
387
|
+
}
|