@inixiative/atlas 0.4.1 → 0.5.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.
- package/README.md +141 -46
- package/examples/atlas-config/README.md +4 -3
- package/examples/atlas-config/config.ts +10 -2
- package/examples/ci/README.md +3 -3
- package/examples/ci/github-actions-incremental.yml +14 -12
- package/examples/ci/github-actions.yml +9 -8
- package/examples/ci/pre-commit +14 -12
- package/package.json +6 -6
- package/src/analyze.ts +120 -7
- package/src/cli.ts +72 -17
- package/src/commands/check.ts +10 -2
- package/src/commands/coverage.ts +8 -1
- package/src/commands/init.ts +78 -0
- package/src/commands/report.ts +0 -0
- package/src/commands/setup.ts +66 -22
- package/src/commands/stamp.ts +99 -31
- package/src/config/defineConfig.ts +10 -2
- package/src/config/load.ts +58 -2
- package/src/fs/walk.ts +90 -17
- package/src/hook/cachedGraph.ts +4 -1
- package/src/hook/claudeCode.ts +1 -1
- package/src/hook/neighbourhood.ts +3 -3
- package/src/index.ts +21 -1
- package/src/parse/parseAtlasBlock.ts +102 -20
- package/src/stamp/patcher.ts +46 -31
- package/src/syntax/comments.ts +260 -0
package/src/commands/stamp.ts
CHANGED
|
@@ -1,48 +1,87 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { existsSync, lstatSync, realpathSync } from 'node:fs';
|
|
2
|
+
import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
|
|
3
|
+
import { consideredFiles, encodeText, readText, type TextEncoding } from '../analyze.ts';
|
|
2
4
|
import type { LoadedConfig } from '../config/defineConfig.ts';
|
|
3
5
|
import { loadConfig } from '../config/load.ts';
|
|
4
6
|
import { stampFor } from '../config/stamp.ts';
|
|
5
7
|
import { mapLimit } from '../fs/concurrent.ts';
|
|
6
|
-
import {
|
|
7
|
-
import {
|
|
8
|
+
import { applyStamp, type StampMode, type StampSkip } from '../stamp/patcher.ts';
|
|
9
|
+
import type { CommentStyle } from '../syntax/comments.ts';
|
|
8
10
|
|
|
9
|
-
|
|
11
|
+
// `before`/`after` are the text; `encoding` is how the file stores it (written back the same way).
|
|
12
|
+
export type StampChange = { path: string; before: string; after: string; encoding?: TextEncoding };
|
|
10
13
|
export type Unresolved = { file: string; category: string; value: string };
|
|
11
|
-
export type
|
|
14
|
+
export type Skipped = { file: string; reason: StampSkip };
|
|
15
|
+
export type StampResult = { changes: StampChange[]; unresolved: Unresolved[]; skipped: Skipped[] };
|
|
12
16
|
|
|
13
17
|
const IO_CONCURRENCY = 64;
|
|
14
18
|
|
|
15
|
-
// A file is in scope when no target is given, when
|
|
16
|
-
//
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
if (
|
|
20
|
-
|
|
21
|
-
|
|
19
|
+
// A file is in scope when no target is given, when a target IS the file, or when a target is a
|
|
20
|
+
// folder the file lives under. Targets are repo-relative and may be written `./src`, `src/` or
|
|
21
|
+
// `.` (the whole repo), as a shell or `dirname` produces them.
|
|
22
|
+
export const inScope = (path: string, targets: string[] = []): boolean => {
|
|
23
|
+
if (targets.length === 0) return true;
|
|
24
|
+
return targets.some((raw) => {
|
|
25
|
+
const target = raw.replace(/^(?:\.\/)+/, '').replace(/\/+$/, '');
|
|
26
|
+
if (target === '' || target === '.') return true;
|
|
27
|
+
return path === target || path.startsWith(`${target}/`);
|
|
28
|
+
});
|
|
29
|
+
};
|
|
30
|
+
|
|
31
|
+
// Command-line targets as repo-relative paths. A target is resolved against the repo root (an
|
|
32
|
+
// absolute path works too) and must exist inside it: a typo'd or outside path would otherwise
|
|
33
|
+
// scope a check to nothing and pass. It is read in its on-disk spelling, so `SRC/a.ts` on a
|
|
34
|
+
// case-insensitive disk still scopes to `src/a.ts`.
|
|
35
|
+
const onDisk = (path: string): string => {
|
|
36
|
+
const link = lstatSync(path).isSymbolicLink();
|
|
37
|
+
return link
|
|
38
|
+
? join(realpathSync.native(dirname(path)), basename(path))
|
|
39
|
+
: realpathSync.native(path);
|
|
40
|
+
};
|
|
41
|
+
export const resolveTargets = (root: string, raw: string[]): string[] => {
|
|
42
|
+
if (raw.length === 0) return [];
|
|
43
|
+
if (!existsSync(root)) throw new Error(`no such directory: ${root}`);
|
|
44
|
+
// the root itself is resolved fully, link included (a project registered through a symlink)
|
|
45
|
+
const realRoot = realpathSync.native(resolve(root));
|
|
46
|
+
return raw.map((target) => {
|
|
47
|
+
const absolute = resolve(root, target);
|
|
48
|
+
try {
|
|
49
|
+
lstatSync(absolute);
|
|
50
|
+
} catch {
|
|
51
|
+
throw new Error(`no such file or folder: ${target}`);
|
|
52
|
+
}
|
|
53
|
+
// the root itself (`.`, or the root path when it is a symlink) is the whole repo
|
|
54
|
+
if (absolute === resolve(root)) return '.';
|
|
55
|
+
const rel = relative(realRoot, onDisk(absolute));
|
|
56
|
+
if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel))
|
|
57
|
+
throw new Error(`target is outside the repo root: ${target}`);
|
|
58
|
+
return rel === '' ? '.' : rel.replaceAll(sep, '/');
|
|
59
|
+
});
|
|
22
60
|
};
|
|
23
61
|
|
|
24
62
|
// Pure: what stamping a file WOULD do, or null if it's already up to date.
|
|
25
63
|
export const computeStamp = (
|
|
26
|
-
path: string,
|
|
64
|
+
file: { path: string; style: CommentStyle },
|
|
27
65
|
source: string,
|
|
28
66
|
config: LoadedConfig,
|
|
29
67
|
mode: StampMode,
|
|
30
68
|
): StampChange | null => {
|
|
69
|
+
const { path } = file;
|
|
31
70
|
const resolved = stampFor(path, config.stamp, config.concepts);
|
|
32
|
-
const { content, changed } = applyStamp(source, resolved, mode);
|
|
71
|
+
const { content, changed } = applyStamp(source, resolved, file, mode);
|
|
33
72
|
return changed ? { path, before: source, after: content } : null;
|
|
34
73
|
};
|
|
35
74
|
|
|
36
75
|
// Pure: the full change plan over an in-memory file set, scoped by target.
|
|
37
76
|
export const planStamp = (
|
|
38
|
-
files: { path: string; source: string }[],
|
|
77
|
+
files: { path: string; style: CommentStyle; source: string }[],
|
|
39
78
|
config: LoadedConfig,
|
|
40
79
|
mode: StampMode,
|
|
41
|
-
|
|
80
|
+
targets: string[] = [],
|
|
42
81
|
): StampChange[] =>
|
|
43
82
|
files
|
|
44
|
-
.filter((f) => inScope(f.path,
|
|
45
|
-
.map((f) => computeStamp(f
|
|
83
|
+
.filter((f) => inScope(f.path, targets))
|
|
84
|
+
.map((f) => computeStamp(f, f.source, config, mode))
|
|
46
85
|
.filter((c): c is StampChange => c !== null);
|
|
47
86
|
|
|
48
87
|
// IO: read the scoped files, plan, and (only with write) persist. Dry-run is
|
|
@@ -52,26 +91,55 @@ export const planStamp = (
|
|
|
52
91
|
// to no concept — leaving a file under-stamped — is visible at write time.
|
|
53
92
|
export const runStamp = async (
|
|
54
93
|
root: string,
|
|
55
|
-
opts: { mode: StampMode;
|
|
94
|
+
opts: { mode: StampMode; targets?: string[]; write: boolean },
|
|
56
95
|
): Promise<StampResult> => {
|
|
57
96
|
const config = await loadConfig(root);
|
|
58
|
-
const
|
|
59
|
-
|
|
60
|
-
)
|
|
61
|
-
|
|
62
|
-
path
|
|
63
|
-
|
|
64
|
-
|
|
97
|
+
const scoped = (await consideredFiles(root, config)).filter((f) => inScope(f.path, opts.targets));
|
|
98
|
+
// A file with no comment style is tagged by its path; there is nothing to write into it.
|
|
99
|
+
const read = await mapLimit(scoped, IO_CONCURRENCY, async ({ path, style }) => {
|
|
100
|
+
if (!style) return null;
|
|
101
|
+
const read = await readText(root, path);
|
|
102
|
+
return read === null
|
|
103
|
+
? null
|
|
104
|
+
: { path, style, source: read.text, encoding: read.encoding, exact: read.exact };
|
|
105
|
+
});
|
|
106
|
+
const files = read.filter((f) => f !== null);
|
|
65
107
|
|
|
66
|
-
const changes =
|
|
108
|
+
const changes: StampChange[] = [];
|
|
109
|
+
const skipped: Skipped[] = [];
|
|
110
|
+
// the rules' result for each file, used for the stamp and for the unresolved report
|
|
111
|
+
const rules = new Map(
|
|
112
|
+
scoped.map(
|
|
113
|
+
(f) =>
|
|
114
|
+
[
|
|
115
|
+
f.path,
|
|
116
|
+
f.style === null ? f.stamp : stampFor(f.path, config.stamp, config.concepts),
|
|
117
|
+
] as const,
|
|
118
|
+
),
|
|
119
|
+
);
|
|
120
|
+
for (const file of files) {
|
|
121
|
+
const resolved = rules.get(file.path) ?? stampFor(file.path, config.stamp, config.concepts);
|
|
122
|
+
const result = applyStamp(file.source, resolved, file, opts.mode);
|
|
123
|
+
if (result.changed && !file.exact) skipped.push({ file: file.path, reason: 'encoding' });
|
|
124
|
+
else if (result.changed)
|
|
125
|
+
changes.push({
|
|
126
|
+
path: file.path,
|
|
127
|
+
before: file.source,
|
|
128
|
+
after: result.content,
|
|
129
|
+
encoding: file.encoding,
|
|
130
|
+
});
|
|
131
|
+
else if (result.skipped) skipped.push({ file: file.path, reason: result.skipped });
|
|
132
|
+
}
|
|
67
133
|
const unresolved: Unresolved[] = [];
|
|
68
|
-
for (const
|
|
69
|
-
for (const u of
|
|
134
|
+
for (const [path, stamp] of rules) {
|
|
135
|
+
for (const u of stamp.unresolved) {
|
|
70
136
|
unresolved.push({ file: path, category: u.category, value: u.value });
|
|
71
137
|
}
|
|
72
138
|
}
|
|
73
139
|
|
|
74
140
|
if (opts.write)
|
|
75
|
-
await mapLimit(changes, IO_CONCURRENCY, (c) =>
|
|
76
|
-
|
|
141
|
+
await mapLimit(changes, IO_CONCURRENCY, (c) =>
|
|
142
|
+
Bun.write(resolve(root, c.path), encodeText(c.after, c.encoding ?? 'utf-8')),
|
|
143
|
+
);
|
|
144
|
+
return { changes, unresolved, skipped };
|
|
77
145
|
};
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { ConceptRegistry, Thesaurus } from '../registry/types.ts';
|
|
2
|
+
import type { CommentTable } from '../syntax/comments.ts';
|
|
2
3
|
|
|
3
4
|
// `partOfFor` is a LAZY descriptor, not a value. The consumer's config.ts can
|
|
4
5
|
// reference it before the concept registry is loaded; the stamp engine resolves it
|
|
@@ -49,17 +50,24 @@ export type ReferenceResolver = (value: string) => string;
|
|
|
49
50
|
type ConfigDefaults = {
|
|
50
51
|
stamp: StampRule[]; // path → tag rules
|
|
51
52
|
ignore: string[]; // files exempt from presence + stamping (tests, barrels)
|
|
52
|
-
include: string[]; // file globs atlas considers (default: common source files)
|
|
53
53
|
references: Record<string, ReferenceResolver>;
|
|
54
54
|
};
|
|
55
55
|
|
|
56
|
-
export type AtlasConfigInput = Partial<ConfigDefaults
|
|
56
|
+
export type AtlasConfigInput = Partial<ConfigDefaults> & {
|
|
57
|
+
// file globs atlas considers. Unset: every file in a comment style atlas knows, plus every
|
|
58
|
+
// file a stamp rule tags by its path.
|
|
59
|
+
include?: string[];
|
|
60
|
+
// more files per comment style: `{ hash: ['.nix', 'Tiltfile'] }` (`.ext` or an exact name)
|
|
61
|
+
comments?: CommentTable;
|
|
62
|
+
};
|
|
57
63
|
|
|
58
64
|
export const defineConfig = (config: AtlasConfigInput): AtlasConfigInput => config;
|
|
59
65
|
|
|
60
66
|
// What the loader hands the engine once defaults are applied and vocab/registry
|
|
61
67
|
// are loaded from the sibling .atlas/ files.
|
|
62
68
|
export type LoadedConfig = ConfigDefaults & {
|
|
69
|
+
include: string[] | null; // null: the default (see AtlasConfigInput.include)
|
|
70
|
+
comments: Required<CommentTable>; // atlas's table merged with the repo's additions
|
|
63
71
|
kinds: readonly string[];
|
|
64
72
|
concepts: ConceptRegistry;
|
|
65
73
|
thesaurus: Thesaurus;
|
package/src/config/load.ts
CHANGED
|
@@ -1,9 +1,48 @@
|
|
|
1
1
|
import { resolve } from 'node:path';
|
|
2
|
-
import { DEFAULT_INCLUDE } from '../fs/walk.ts';
|
|
3
2
|
import type { ConceptRegistry, Thesaurus } from '../registry/types.ts';
|
|
3
|
+
import { COMMENT_STYLES, type CommentTable, mergeCommentTable } from '../syntax/comments.ts';
|
|
4
4
|
import { DEFAULT_KINDS } from '../vocab/kinds.ts';
|
|
5
5
|
import type { AtlasConfigInput, LoadedConfig } from './defineConfig.ts';
|
|
6
6
|
|
|
7
|
+
// `.atlas/**/*.ts` imports `@inixiative/atlas` (defineConfig, partOfFor, DEFAULT_KINDS). Bind those
|
|
8
|
+
// imports to the atlas that is running, so the config loads in a repo with no package.json or
|
|
9
|
+
// node_modules (`bunx @inixiative/atlas check` in a Python repo) and never against another
|
|
10
|
+
// installed version. Bun's runtime plugins ignore onResolve for bare imports, so the specifier
|
|
11
|
+
// is rewritten on load.
|
|
12
|
+
const SELF: Record<string, string> = {
|
|
13
|
+
'@inixiative/atlas': resolve(import.meta.dir, '../index.ts'),
|
|
14
|
+
'@inixiative/atlas/config': resolve(import.meta.dir, './defineConfig.ts'),
|
|
15
|
+
};
|
|
16
|
+
// only a module specifier: `from '…'`, `import '…'`, `import('…')`, never another string literal
|
|
17
|
+
const ATLAS_IMPORT = /(\bfrom\s*|\bimport\s*\(?\s*)(['"])(@inixiative\/atlas(?:\/config)?)\2/g;
|
|
18
|
+
|
|
19
|
+
// Rewrite a config file's atlas imports to `paths`. The path is spliced into the file's own
|
|
20
|
+
// string literal, so it is written with forward slashes (a Windows `\` would be read as an
|
|
21
|
+
// escape: `C:\Users\node_modules` → `C:Users<newline>ode_modules`; Bun accepts `C:/…`) and the
|
|
22
|
+
// literal's quote is escaped (an install under `O'Brien/`).
|
|
23
|
+
export const bindAtlasImports = (source: string, paths: Record<string, string> = SELF): string =>
|
|
24
|
+
source.replace(ATLAS_IMPORT, (match, keyword: string, quote: string, specifier: string) => {
|
|
25
|
+
const path = paths[specifier];
|
|
26
|
+
if (!path) return match;
|
|
27
|
+
return `${keyword}${quote}${path.replaceAll('\\', '/').replaceAll(quote, `\\${quote}`)}${quote}`;
|
|
28
|
+
});
|
|
29
|
+
|
|
30
|
+
let bound = false;
|
|
31
|
+
const bindSelfImports = (): void => {
|
|
32
|
+
if (bound) return;
|
|
33
|
+
bound = true;
|
|
34
|
+
Bun.plugin({
|
|
35
|
+
name: 'atlas-config-self',
|
|
36
|
+
target: 'bun',
|
|
37
|
+
setup(build) {
|
|
38
|
+
build.onLoad({ filter: /[\\/]\.atlas[\\/].+\.[cm]?ts$/ }, async ({ path }) => ({
|
|
39
|
+
loader: 'ts',
|
|
40
|
+
contents: bindAtlasImports(await Bun.file(path).text()),
|
|
41
|
+
}));
|
|
42
|
+
},
|
|
43
|
+
});
|
|
44
|
+
};
|
|
45
|
+
|
|
7
46
|
// Import a `.atlas/` file if it exists; missing files are optional (atlas ships
|
|
8
47
|
// defaults for vocab), but a present file with a real error propagates.
|
|
9
48
|
const loadModule = async (path: string): Promise<Record<string, unknown> | null> => {
|
|
@@ -24,10 +63,26 @@ const named = <T>(
|
|
|
24
63
|
throw new Error(`.atlas/${file} exists but exports none of: ${names.join(', ')}`);
|
|
25
64
|
};
|
|
26
65
|
|
|
66
|
+
// `comments` names styles atlas has; a typo would silently tag nothing, so refuse it.
|
|
67
|
+
const validComments = (comments: CommentTable | undefined): CommentTable | undefined => {
|
|
68
|
+
for (const [style, entries] of Object.entries(comments ?? {})) {
|
|
69
|
+
if (!(style in COMMENT_STYLES))
|
|
70
|
+
throw new Error(
|
|
71
|
+
`.atlas/config.ts: comments.${style} is not a comment style (${Object.keys(COMMENT_STYLES).join(', ')})`,
|
|
72
|
+
);
|
|
73
|
+
if (!Array.isArray(entries) || entries.some((e) => typeof e !== 'string' || e === ''))
|
|
74
|
+
throw new Error(
|
|
75
|
+
`.atlas/config.ts: comments.${style} must list '.ext' extensions or file names`,
|
|
76
|
+
);
|
|
77
|
+
}
|
|
78
|
+
return comments;
|
|
79
|
+
};
|
|
80
|
+
|
|
27
81
|
// Load the consumer's `.atlas/` config: kinds → concepts → thesaurus → config (no
|
|
28
82
|
// evaluation-order coupling, since partOfFor is a lazy descriptor). atlas ships
|
|
29
83
|
// the kinds defaults; the repo OWNS concepts.ts and the optional thesaurus.ts.
|
|
30
84
|
export const loadConfig = async (root: string): Promise<LoadedConfig> => {
|
|
85
|
+
bindSelfImports();
|
|
31
86
|
const dir = resolve(root, '.atlas');
|
|
32
87
|
const [kindsMod, conceptsMod, thesaurusMod, configMod] = await Promise.all([
|
|
33
88
|
loadModule(resolve(dir, 'kinds.ts')),
|
|
@@ -71,12 +126,13 @@ export const loadConfig = async (root: string): Promise<LoadedConfig> => {
|
|
|
71
126
|
}
|
|
72
127
|
|
|
73
128
|
return {
|
|
129
|
+
include: cfg.include ?? null,
|
|
130
|
+
comments: mergeCommentTable(validComments(cfg.comments)),
|
|
74
131
|
kinds,
|
|
75
132
|
concepts,
|
|
76
133
|
thesaurus,
|
|
77
134
|
stamp: cfg.stamp ?? [],
|
|
78
135
|
ignore: cfg.ignore ?? [],
|
|
79
|
-
include: cfg.include ?? DEFAULT_INCLUDE,
|
|
80
136
|
references: cfg.references ?? {},
|
|
81
137
|
};
|
|
82
138
|
};
|
package/src/fs/walk.ts
CHANGED
|
@@ -1,26 +1,99 @@
|
|
|
1
|
+
import { existsSync, lstatSync } from 'node:fs';
|
|
2
|
+
import { resolve } from 'node:path';
|
|
1
3
|
import { Glob } from 'bun';
|
|
2
4
|
import { matchesAny } from '../config/glob.ts';
|
|
3
5
|
|
|
4
|
-
|
|
6
|
+
// Never considered, whatever the config says. Dotdirs are walked (`.claude/`, `.github/` carry
|
|
7
|
+
// real work); these aren't. `.atlas/` is the config itself; MAP.md, COVERAGE.md and atlas.html
|
|
8
|
+
// are what `generate` and `report` write (stamping one would fight the next generate); a pnpm
|
|
9
|
+
// lockfile is generated and pnpm strips comments from it.
|
|
10
|
+
export const ALWAYS_IGNORE = [
|
|
11
|
+
'**/node_modules/**',
|
|
12
|
+
'**/.git/**',
|
|
13
|
+
'**/dist/**',
|
|
14
|
+
'**/.atlas/**',
|
|
15
|
+
'MAP.md', // generate writes it at the root only
|
|
16
|
+
'**/COVERAGE.md', // report writes these wherever --out points
|
|
17
|
+
'**/atlas.html',
|
|
18
|
+
'**/pnpm-lock.yaml',
|
|
19
|
+
];
|
|
5
20
|
|
|
6
|
-
|
|
7
|
-
|
|
21
|
+
const git = async (root: string, args: string[]) => {
|
|
22
|
+
let proc: ReturnType<typeof Bun.spawn>;
|
|
23
|
+
try {
|
|
24
|
+
// LC_ALL=C: git's messages are read below, and a translated git words them differently
|
|
25
|
+
proc = Bun.spawn(['git', ...args], {
|
|
26
|
+
cwd: root,
|
|
27
|
+
stdout: 'pipe',
|
|
28
|
+
stderr: 'pipe',
|
|
29
|
+
env: { ...process.env, LC_ALL: 'C' },
|
|
30
|
+
});
|
|
31
|
+
} catch {
|
|
32
|
+
throw new Error('atlas lists files with git, and git is not installed');
|
|
33
|
+
}
|
|
34
|
+
const [out, err, code] = await Promise.all([
|
|
35
|
+
new Response(proc.stdout as ReadableStream).text(),
|
|
36
|
+
new Response(proc.stderr as ReadableStream).text(),
|
|
37
|
+
proc.exited,
|
|
38
|
+
]);
|
|
39
|
+
return { out, err: err.trim(), code };
|
|
40
|
+
};
|
|
8
41
|
|
|
9
|
-
//
|
|
10
|
-
//
|
|
42
|
+
// What git would commit: tracked files plus untracked ones that aren't ignored, so a new file is
|
|
43
|
+
// seen before it's added and generated output under .gitignore never is. Null when the root is
|
|
44
|
+
// not part of a repo: outside any work tree, or a folder the enclosing repo ignores (a scratch
|
|
45
|
+
// dir). Any other git failure (`safe.directory`, a broken index) is an error, never a silent
|
|
46
|
+
// switch to listing every file.
|
|
47
|
+
const gitFiles = async (root: string): Promise<string[] | null> => {
|
|
48
|
+
const inside = await git(root, ['rev-parse', '--is-inside-work-tree']);
|
|
49
|
+
if (inside.code !== 0) {
|
|
50
|
+
if (/not a git repository/i.test(inside.err)) return null;
|
|
51
|
+
throw new Error(`git rev-parse failed in ${root}: ${inside.err}`);
|
|
52
|
+
}
|
|
53
|
+
if (inside.out.trim() !== 'true') return null; // inside a .git dir or a bare repo
|
|
54
|
+
if ((await git(root, ['check-ignore', '-q', '.'])).code === 0) return null;
|
|
55
|
+
const listed = await git(root, ['ls-files', '-z', '--cached', '--others', '--exclude-standard']);
|
|
56
|
+
if (listed.code !== 0) throw new Error(`git ls-files failed in ${root}: ${listed.err}`);
|
|
57
|
+
// An untracked nested repo or worktree is listed as `dir/`; it isn't a file of this repo.
|
|
58
|
+
// A submodule is a gitlink, not a file, so its contents aren't walked either.
|
|
59
|
+
return [...new Set(listed.out.split('\0'))].filter((p) => p !== '' && !p.endsWith('/'));
|
|
60
|
+
};
|
|
61
|
+
|
|
62
|
+
// A directory that isn't part of a repo (a fixture, an unpacked tarball, a fresh docs folder):
|
|
63
|
+
// every file in it.
|
|
64
|
+
const allFiles = async (root: string): Promise<string[]> => {
|
|
65
|
+
const files: string[] = [];
|
|
66
|
+
for await (const entry of new Glob('**/*').scan({ cwd: root, onlyFiles: true, dot: true }))
|
|
67
|
+
files.push(entry.replaceAll('\\', '/'));
|
|
68
|
+
return files;
|
|
69
|
+
};
|
|
70
|
+
|
|
71
|
+
// A regular file, not a symlink: a link may point outside the repo (stamp would write there) or
|
|
72
|
+
// at another listed file (stamped twice). Deleted-but-indexed files are skipped too.
|
|
73
|
+
const isFile = (root: string, path: string): boolean => {
|
|
74
|
+
try {
|
|
75
|
+
return lstatSync(resolve(root, path)).isFile();
|
|
76
|
+
} catch {
|
|
77
|
+
return false;
|
|
78
|
+
}
|
|
79
|
+
};
|
|
80
|
+
|
|
81
|
+
// Repo-relative files not ignored, sorted for deterministic output. `keep` decides which of the
|
|
82
|
+
// rest atlas considers (an include list, or the default in analyze.ts).
|
|
11
83
|
export const walkFiles = async (
|
|
12
84
|
root: string,
|
|
13
|
-
|
|
14
|
-
|
|
85
|
+
ignore: string[],
|
|
86
|
+
keep: (path: string) => boolean,
|
|
15
87
|
): Promise<string[]> => {
|
|
16
|
-
|
|
17
|
-
const
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
88
|
+
if (!existsSync(root)) throw new Error(`no such directory: ${root}`);
|
|
89
|
+
const listed = (await gitFiles(root)) ?? (await allFiles(root));
|
|
90
|
+
return listed
|
|
91
|
+
.filter(
|
|
92
|
+
(path) =>
|
|
93
|
+
!matchesAny(ALWAYS_IGNORE, path) &&
|
|
94
|
+
!matchesAny(ignore, path) &&
|
|
95
|
+
keep(path) &&
|
|
96
|
+
isFile(root, path),
|
|
97
|
+
)
|
|
98
|
+
.sort();
|
|
26
99
|
};
|
package/src/hook/cachedGraph.ts
CHANGED
|
@@ -20,9 +20,12 @@ const cachePathFor = (root: string, cacheDir: string, version: string): string =
|
|
|
20
20
|
);
|
|
21
21
|
|
|
22
22
|
// A `.atlas/` edit (new concept, new rule) makes the cached graph wrong before the TTL does.
|
|
23
|
+
// Every file under `.atlas/`, helpers in subfolders included (their imports load too).
|
|
23
24
|
const configNewerThan = (root: string, mtimeMs: number): boolean => {
|
|
24
25
|
const dir = join(root, '.atlas');
|
|
25
|
-
return readdirSync(dir
|
|
26
|
+
return readdirSync(dir, { recursive: true }).some(
|
|
27
|
+
(entry) => statSync(join(dir, String(entry))).mtimeMs > mtimeMs,
|
|
28
|
+
);
|
|
26
29
|
};
|
|
27
30
|
|
|
28
31
|
// The hooks fire on every Read/Grep and a full analyze walks the whole tree (seconds on a
|
package/src/hook/claudeCode.ts
CHANGED
|
@@ -20,7 +20,7 @@ export const toAdditionalContext = (text: string): string => {
|
|
|
20
20
|
if (trimmed === '') return '';
|
|
21
21
|
const body =
|
|
22
22
|
trimmed.length > MAX_CHARS
|
|
23
|
-
? `${trimmed.slice(0, MAX_CHARS)}\n… (truncated; bunx atlas query --partOf <concept> lists the rest)`
|
|
23
|
+
? `${trimmed.slice(0, MAX_CHARS)}\n… (truncated; bunx @inixiative/atlas query --partOf <concept> lists the rest)`
|
|
24
24
|
: trimmed;
|
|
25
25
|
return JSON.stringify({
|
|
26
26
|
suppressOutput: true,
|
|
@@ -73,7 +73,7 @@ export const renderNeighbourhood = (
|
|
|
73
73
|
siblings.length > SIBLING_SAMPLE ? [` … ${siblings.length - SIBLING_SAMPLE} more`] : [];
|
|
74
74
|
const consumers = graph.usesConsumers[concept]?.length ?? 0;
|
|
75
75
|
return [
|
|
76
|
-
`${concept} — ${siblings.length} other file(s)${consumers > 0 ? `, ${consumers} consumer(s) via @uses` : ''}; \`bunx atlas query --partOf ${concept}\` lists all`,
|
|
76
|
+
`${concept} — ${siblings.length} other file(s)${consumers > 0 ? `, ${consumers} consumer(s) via @uses` : ''}; \`bunx @inixiative/atlas query --partOf ${concept}\` lists all`,
|
|
77
77
|
...sample,
|
|
78
78
|
...more,
|
|
79
79
|
].join('\n');
|
|
@@ -81,7 +81,7 @@ export const renderNeighbourhood = (
|
|
|
81
81
|
const usesBlock =
|
|
82
82
|
membership.uses.length > 0
|
|
83
83
|
? [
|
|
84
|
-
`@uses ${membership.uses.join(', ')} — load-bearing dependencies; \`bunx atlas query --partOf <concept>\` shows what implements each`,
|
|
84
|
+
`@uses ${membership.uses.join(', ')} — load-bearing dependencies; \`bunx @inixiative/atlas query --partOf <concept>\` shows what implements each`,
|
|
85
85
|
]
|
|
86
86
|
: [];
|
|
87
87
|
const kinds = kindLines(graph, relPath, membership.partOf, options.kinds ?? REACH_KINDS);
|
|
@@ -230,7 +230,7 @@ const conceptBlock = (graph: Graph, concept: string, label: string): string => {
|
|
|
230
230
|
const consumers = graph.usesConsumers[concept]?.length ?? 0;
|
|
231
231
|
const doc = graph.thesaurus[concept]?.doc;
|
|
232
232
|
return [
|
|
233
|
-
`${concept}${label} — ${files.length} file(s)${consumers > 0 ? `, ${consumers} consumer(s) via @uses` : ''}; \`bunx atlas query --partOf ${concept}\` lists all`,
|
|
233
|
+
`${concept}${label} — ${files.length} file(s)${consumers > 0 ? `, ${consumers} consumer(s) via @uses` : ''}; \`bunx @inixiative/atlas query --partOf ${concept}\` lists all`,
|
|
234
234
|
...(doc ? [` read: ${doc}`] : []),
|
|
235
235
|
...sample,
|
|
236
236
|
...more,
|
package/src/index.ts
CHANGED
|
@@ -4,8 +4,10 @@ export type { Graph } from './commands/graph.ts';
|
|
|
4
4
|
export {
|
|
5
5
|
atlasHookEntry,
|
|
6
6
|
CLAUDE_SETTINGS,
|
|
7
|
+
type HookRunner,
|
|
7
8
|
hookCommandFor,
|
|
8
9
|
mergeAtlasHooks,
|
|
10
|
+
runnerFor,
|
|
9
11
|
type SetupReport,
|
|
10
12
|
setupClaudeHooks,
|
|
11
13
|
} from './commands/setup.ts';
|
|
@@ -35,7 +37,13 @@ export {
|
|
|
35
37
|
renderConceptMatches,
|
|
36
38
|
renderNeighbourhood,
|
|
37
39
|
} from './hook/neighbourhood.ts';
|
|
38
|
-
export {
|
|
40
|
+
export {
|
|
41
|
+
type AtlasAnnotation,
|
|
42
|
+
type LocatedBlock,
|
|
43
|
+
locateAtlasBlock,
|
|
44
|
+
parseAtlasBlock,
|
|
45
|
+
type UsesState,
|
|
46
|
+
} from './parse/parseAtlasBlock.ts';
|
|
39
47
|
export { invert } from './registry/invert.ts';
|
|
40
48
|
export {
|
|
41
49
|
type ConceptEntry,
|
|
@@ -45,4 +53,16 @@ export {
|
|
|
45
53
|
type Thesaurus,
|
|
46
54
|
type ThesaurusEntry,
|
|
47
55
|
} from './registry/types.ts';
|
|
56
|
+
export {
|
|
57
|
+
COMMENT_STYLES,
|
|
58
|
+
COMMENT_TABLE,
|
|
59
|
+
type CommentStyle,
|
|
60
|
+
type CommentStyleName,
|
|
61
|
+
type CommentTable,
|
|
62
|
+
entryFor,
|
|
63
|
+
mergeCommentTable,
|
|
64
|
+
preambleEnd,
|
|
65
|
+
styleFor,
|
|
66
|
+
styleNameFor,
|
|
67
|
+
} from './syntax/comments.ts';
|
|
48
68
|
export { DEFAULT_KINDS, type DefaultKind } from './vocab/kinds.ts';
|